diff options
Diffstat (limited to 'user_guide_src/source/libraries/encryption.rst')
| -rw-r--r-- | user_guide_src/source/libraries/encryption.rst | 39 |
1 files changed, 18 insertions, 21 deletions
diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index a4415f510..f29ebf4ed 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -5,13 +5,13 @@ Encryption Library The Encryption Library provides two-way data encryption. To do so in a cryptographically secure way, it utilizes PHP extensions that are unfortunately not always available on all systems. -You must meet one of the following dependancies in order to use this +You must meet one of the following dependencies in order to use this library: - `OpenSSL <http://php.net/openssl>`_ (and PHP 5.3.3) - `MCrypt <http://php.net/mcrypt>`_ (and `MCRYPT_DEV_URANDOM` availability) -If neither of the above dependancies is met, we simply cannot offer +If neither of the above dependencies is met, we simply cannot offer you a good enough implementation to meet the high standards required for proper cryptography. @@ -84,14 +84,19 @@ your server is not totally under your control it's impossible to ensure key security so you may want to think carefully before using it for anything that requires high security, like storing credit card numbers. -Your encryption key should be as long as the encyption algorithm in use -allows. For AES-128, that's 128 bits or 16 bytes (charcters) long. The -key should be as random as possible and it should **not** be a simple -text string. - +Your encryption key **must** be as long as the encyption algorithm in use +allows. For AES-128, that's 128 bits or 16 bytes (charcters) long. You will find a table below that shows the supported key lengths of different ciphers. +The key should be as random as possible and it **must not** be a regular +text string, nor the output of a hashing function, etc. In order to create +a proper key, you must use the Encryption library's ``create_key()`` method +:: + + // $key will be assigned a 16-byte (128-bit) random key + $key = $this->encryption->create_key(16); + The key can be either stored in your *application/config/config.php*, or you can design your own storage mechanism and pass the key dynamically when encrypting/decrypting. @@ -168,9 +173,9 @@ but regardless, here's a list of most of them: ============== ========= ============================== ========================================= Cipher name Driver Key lengths (bits / bytes) Supported modes ============== ========= ============================== ========================================= -AES-128 OpenSSL 128 / 16 CBC, CTR, CFB, CFB8, OFB, ECB, GCM, XTS -AES-192 OpenSSL 192 / 24 CBC, CTR, CFB, CFB8, OFB, ECB, GCM, XTS -AES-256 OpenSSL 256 / 32 CBC, CTR, CFB, CFB8, OFB, ECB, GCM, XTS +AES-128 OpenSSL 128 / 16 CBC, CTR, CFB, CFB8, OFB, ECB, XTS +AES-192 OpenSSL 192 / 24 CBC, CTR, CFB, CFB8, OFB, ECB, XTS +AES-256 OpenSSL 256 / 32 CBC, CTR, CFB, CFB8, OFB, ECB, XTS Rijndael-128 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB Rijndael-192 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB Rijndael-256 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB @@ -234,7 +239,6 @@ CFB8 cfb8 MCrypt, OpenSSL Same as CFB, but operates in 8- OFB ofb MCrypt, OpenSSL N/A OFB8 ofb8 MCrypt Same as OFB, but operates in 8-bit mode (not recommended). ECB ecb MCrypt, OpenSSL Ignores IV (not recommended). -GCM gcm OpenSSL Provides authentication and therefore doesn't need a HMAC. XTS xts OpenSSL Usually used for encrypting random access data such as RAM or hard-disk storage. Stream stream MCrypt, OpenSSL This is not actually a mode, it just says that a stream cipher is being used. Required because of the general cipher+mode initialization process. =========== ================== ================= =================================================================================================================================================== @@ -246,10 +250,9 @@ It's probably important for you to know that an encrypted string is usually longer than the original, plain-text string (depending on the cipher). This is influenced by the cipher algorithm itself, the IV prepended to the -cipher-text and (unless you are using GCM mode) the HMAC authentication -message that is also prepended. Furthermore, the encrypted message is also -Base64-encoded so that it is safe for storage and transmission, regardless -of a possible character set in use. +cipher-text and the HMAC authentication message that is also prepended. +Furthermore, the encrypted message is also Base64-encoded so that it is safe +for storage and transmission, regardless of a possible character set in use. Keep this information in mind when selecting your data storage mechanism. Cookies, for example, can only hold 4K of information. @@ -425,9 +428,6 @@ Option Default value Mandatory / Optional Description cipher N/A Yes Encryption algorithm (see :ref:`ciphers-and-modes`). mode N/A Yes Encryption mode (see :ref:`encryption-modes`). key N/A Yes Encryption key. -iv N/A No Initialization vector (IV). - If not provided it will be automatically generated - during encryption and looked for during decryption. hmac TRUE No Whether to use a HMAC. Boolean. If set to FALSE, then *hmac_digest* and *hmac_key* will be ignored. @@ -444,9 +444,6 @@ raw_data FALSE No Whether the cipher-t value is incorrect. This includes *hmac_key*, unless *hmac* is set to FALSE. -.. note:: If GCM mode is used, *hmac* will always be FALSE. This is - because GCM mode itself provides authentication. - .. _digests: Supported HMAC authentication algorithms |