diff options
Diffstat (limited to 'user_guide_src')
| -rw-r--r-- | user_guide_src/source/libraries/encryption.rst | 555 |
1 files changed, 555 insertions, 0 deletions
diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst new file mode 100644 index 000000000..cedc8d381 --- /dev/null +++ b/user_guide_src/source/libraries/encryption.rst @@ -0,0 +1,555 @@ +################## +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 +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 +you a good enough implementation to meet the high standards required +for proper cryptography. + +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +**************************** +Using the Encryption Library +**************************** + +Initializing the Class +====================== + +Like most other classes in CodeIgniter, the Encryption library is +initialized in your controller using the ``$this->load->library()`` +method:: + + $this->load->library('encrypt'); + +Once loaded, the Encryption library object will be available using:: + + $this->encrypt + +Default behavior +================ + +By default, the Encryption Library will use the AES-128 cipher in CBC +mode, using your configured *encryption_key* and SHA512 HMAC authentication. + +.. note:: AES-128 is chosen both because it is proven to be strong and + because of its wide availability across different cryptographic + software and programming languages' APIs. + +However, the *encryption_key* is not used as is. + +If you are somewhat familiar with cryptography, you should already know +that a HMAC also requires a secret key and using the same key for both +encryption and authentication is a bad practice. + +Because of that, two separate keys are derived from your already configured +*encryption_key*: one for encryption and one for authentication. This is +done via a technique called `HMAC-based Key Derivation Function +<http://en.wikipedia.org/wiki/HKDF>`_ (HKDF). + +Setting your encryption_key +=========================== + +An *encryption key* is a piece of information that controls the +cryptographic process and permits a plain-text string to be encrypted, +and afterwards - decrypted. It is the secret "ingredient" in the whole +process that allows you to be the only one who is able to decrypt data +that you've decided to hide from the eyes of the public. +After one key is used to encrypt data, that same key provides the **only** +means to decrypt it, so not only must you chose one carefully, but you +must not lose it or you will also use the encrypted data. + +It must be noted that to ensure maximum security, such key *should* not +only be as strong as possible, but also often changed. Such behavior +however is rarely practical or possible to implement, and that is why +CodeIgniter gives you the ability to configure a single key that is to be +used (almost) every time. + +It goes without saying that you should guard your key carefully. Should +someone gain access to your key, the data will be easily decrypted. If +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. + +You will find a table below that shows the supported key lengths of +different ciphers. + +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. + +To save your key to your *application/config/config.php*, open the file +and set:: + + $config['encryption_key'] = 'YOUR KEY'; + +.. _ciphers-and-modes: + +Supported encryption ciphers and modes +====================================== + +.. note:: The terms 'cipher' and 'encryption algorithm' are interchangeable. + +Portable ciphers +---------------- + +Because MCrypt and OpenSSL (also called drivers throughout this document) +each support different sets of encryption algorithms and often implement +them in different ways, our Encryption library is designed to use them in +a portable fashion, or in other words - it enables you to use them +interchangeably, at least for the ciphers supported by both drivers. + +It is also implemented in a way that aims to match the standard +implementations in other programming languages and libraries. + +Here's a list of the so called "portable" ciphers, where +"CodeIgniter name" is the string value that you'd have to pass to the +Encryption library to use that cipher: + +======================== ================== ============================ =============================== +Cipher name CodeIgniter name Key lengths (bits / bytes) Supported modes +======================== ================== ============================ =============================== +AES-128 / Rijndael-128 aes-128 128 / 16 CBC, CTR, CFB, CFB8, OFB, ECB +AES-192 aes-192 192 / 24 CBC, CTR, CFB, CFB8, OFB, ECB +AES-256 aes-256 256 / 32 CBC, CTR, CFB, CFB8, OFB, ECB +DES des 56 / 7 CBC, CFB, CFB8, OFB, ECB +TripleDES tripledes 56 / 7, 112 / 14, 168 / 21 CBC, CFB, CFB8, OFB +Blowfish blowfish 128-448 / 16-56 CBC, CFB, OFB, ECB +CAST5 / CAST-128 cast5 40-128 / 5-16 CBC, CFB, OFB, ECB +RC4 / ARCFour rc4 40-2048 / 5-256 Stream +======================== ================== ============================ =============================== + +.. important:: Because of how MCrypt works, if you fail to provide a key + with the appropriate length, you might end up using a different + algorithm than the one configured, so be really careful with that! + +.. note:: In case it isn't clear from the above table, Blowfish, CAST5 + and RC4 support variable length keys. That is, any number in the + shown ranges is valid, although in bit terms that only happens + in 8-bit increments. + +.. note:: Even though CAST5 supports key lengths lower than 128 bits + (16 bytes), in fact they will just be zero-padded to the + maximum length, as specified in `RFC 2144 + <http://tools.ietf.org/rfc/rfc2144.txt>`_. + +.. note:: Blowfish supports key lengths as small as 32 bits (4 bytes), but + our tests have shown that only lengths of 128 bits (16 bytes) or + higher are properly supported by both MCrypt and OpenSSL. It is + also a bad practice to use such low-length keys anyway. + +Driver-specific ciphers +----------------------- + +As noted above, MCrypt and OpenSSL support different sets of encryption +ciphers. For portability reasons and because we haven't tested them +properly, we do not advise you to use the ones that are driver-specific, +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 +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 +GOST MCrypt 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB +Twofish MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB +CAST-256 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB +Loki97 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB +SaferPlus MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB +Serpent MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB +XTEA MCrypt 128 / 16 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB +RC2 MCrypt 8-1024 / 1-128 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB +RC2 OpenSSL 8-1024 / 1-128 CBC, CFB, OFB, ECB +Camellia-128 OpenSSL 128 / 16 CBC, CFB, CFB8, OFB, ECB +Camellia-192 OpenSSL 192 / 24 CBC, CFB, CFB8, OFB, ECB +Camellia-256 OpenSSL 256 / 32 CBC, CFB, CFB8, OFB, ECB +Seed OpenSSL 128 / 16 CBC, CFB, OFB, ECB +============== ========= ============================== ========================================= + +.. note:: If you wish to use one of those ciphers, you'd have to pass + its name in lower-case to the Encryption library. + +.. note:: You've probably noticed that all AES cipers (and Rijndael-128) + are also listed in the portable ciphers list. This is because + drivers support different modes for these ciphers. Also, it is + important to note that AES-128 and Rijndael-128 are actually + the same cipher, but **only** when used with a 128-bit key. + +.. note:: RC2 is listed as supported by both MCrypt and OpenSSL. + However, both drivers implement them differently and they + are not portable. It is probably worth noting that we only + found one obscure source confirming that it is MCrypt that + is not properly implementing it. + +.. _encryption-modes: + +Encryption modes +---------------- + +Different modes of encryption have different characteristics and serve +for different purposes. Some are stronger than others, some are faster +and some offer extra features. +We are not going in depth into that here, we'll leave that to the +cryptography experts. The table below is to provide brief informational +reference to our more experienced users. If you are a beginner, just +stick to the CBC mode - it is widely accepted as strong and secure for +general purposes. + +=========== ================== ================= =================================================================================================================================================== +Mode name CodeIgniter name Driver support Additional info +=========== ================== ================= =================================================================================================================================================== +CBC cbc MCrypt, OpenSSL A safe default choice +CTR ctr MCrypt, OpenSSL Considered as theoretically better than CBC, but not as widely available +CFB cfb MCrypt, OpenSSL N/A +CFB8 cfb8 MCrypt, OpenSSL Same as CFB, but operates in 8-bit mode (not recommended). +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. +=========== ================== ================= =================================================================================================================================================== + +Message Length +============== + +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. + +Keep this information in mind when selecting your data storage mechanism. +Cookies, for example, can only hold 4K of information. + +.. _configuration: + +Configuring the library +======================= + +For usability, performance, but also historical reasons tied to our old +:doc:`Encrypt Class <encrypt>`, the Encryption library is designed to +use repeatedly the same driver, encryption cipher, mode and key. + +As noted in the "Default behavior" section above, this means using an +auto-detected driver (OpenSSL has a higher priority), the AES-128 ciper +in CBC mode, and your ``$config['encryption_key']`` value. + +If you wish to change that however, you need to use the ``initialize()`` +method. It accepts an associative array of parameters, all of which are +optional: + +======== =============================================== +Option Possible values +======== =============================================== +driver 'mcrypt', 'openssl' +cipher Cipher name (see :ref:`ciphers-and-modes`) +mode Encryption mode (see :ref:`encryption-modes`) +key Encryption key +======== =============================================== + +For example, if you were to change the encryption algorithm and +mode to AES-256 in CTR mode, this is what you should do:: + + $this->encryption->initialize( + array( + 'cipher' => 'aes-256', + 'mode' => 'ctr', + 'key' => '<a 32-character random string>' + ) + ); + +Note that we only mentioned that you want to change the ciper and mode, +but we also included a key in the example. As previously noted, it is +important that you choose a key with a proper size for the used algorithm. + +There's also the ability to change the driver, if for some reason you +have both, but want to use MCrypt instead of OpenSSL:: + + // Switch to the MCrypt driver + $this->encryption->initialize(array('driver' => 'mcrypt')); + + // Switch back to the OpenSSL driver + $this->encryption->initialize(array('driver' => 'openssl')); + +Encrypting and decrypting data +============================== + +Encrypting and decrypting data with the already configured library +settings is simple. As simple as just passing the string to the +``encrypt()`` and/or ``decrypt()`` methods:: + + $plain_text = 'This is a plain-text message!'; + $ciphertext = $this->encryption->encrypt($plain_text); + + // Outputs: This is a plain-text message! + echo $this->encryption->decrypt($ciphertext); + +And that's it! The Encryption library will do everything necessary +for the whole process to be cryptographically secure out-of-the-box. +You don't need to worry about it. + +.. important:: Both methods will return FALSE in case of an error. + While for ``encrypt()`` this can only mean incorrect + configuration, you should always check the return value + of ``decrypt()`` in production code. + +How it works +------------ + +If you must know how the process works, here's what happens under +the hood: + +- ``$this->encryption->encrypt($plain_text)`` + + #. Derive an encryption key and a HMAC key from your configured + *encryption_key* via HKDF, using the SHA-512 digest algorithm. + + #. Generate a random initialization vector (IV). + + #. Encrypt the data via AES-128 in CBC mode (or another previously + configured cipher and mode), using the above-mentioned derived + encryption key and IV. + + #. Prepend said IV to the resulting cipher-text. + + #. Base64-encode the resulting string, so that it can be safely + stored or transferred without worrying about character sets. + + #. Create a SHA-512 HMAC authentication message using the derived + HMAC key to ensure data integrity and prepend it to the Base64 + string. + +- ``$this->encryption->decrypt($ciphertext)`` + + #. Derive an encryption key and a HMAC key from your configured + *encryption_key* via HKDF, using the SHA-512 digest algorithm. + Because your configured *encryption_key* is the same, this + will produce the same result as in the ``encrypt()`` method + above - otherwise you won't be able to decrypt it. + + #. Check if the string is long enough, separate the HMAC out of + it and validate if it is correct (this is done in a way that + prevents timing attacks agains it). Return FALSE if either of + the checks fails. + + #. Base64-decode the string. + + #. Separate the IV out of the cipher-text and decrypt the said + cipher-text using that IV and the derived encryption key. + +.. _custom-parameters: + +Using custom parameters +----------------------- + +Let's say you have to interact with another system that is out +of your control and uses another method to encrypt data. A +method that will most certainly not match the above-described +sequence and probably not use all of the steps either. + +The Encryption library allows you to change how its encryption +and decryption processes work, so that you can easily tailor a +custom solution for such situations. + +.. note:: It is possible to use the library in this way, without + setting an *encryption_key* in your configuration file. + +All you have to do is to pass an associative array with a few +parameters to either the ``encrypt()`` or ``decrypt()`` method. +Here's an example:: + + // Assume that we have $ciphertext, $key and $hmac_key + // from on outside source + + $message = $this->encryption->decrypt( + $ciphertext, + array( + 'cipher' => 'blowfish', + 'mode' => 'cbc', + 'key' => $key, + 'hmac_digest' => 'sha256', + 'hmac_key' => $hmac_key + ) + ); + +In the above example, we are decrypting a message that was encrypted +using the Blowfish cipher in CBC mode and authenticated via a SHA-256 +HMAC. + +.. important:: Note that both 'key' and 'hmac_key' are used in this + example. When using custom parameters, encryption and HMAC keys + are not derived like the default behavior of the library is. + +Below is a list of the available options. + +However, unless you really need to and you know what you are doing, +we advise you to not change the encryption process as this could +impact security, so please do so with caution. + +============= =============== ============================= ====================================================== +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. +hmac_digest sha512 No HMAC message digest algorithm (see :ref:`digests`). +hmac_key N/A Yes, unless *hmac* is FALSE HMAC key. +raw_data FALSE No Whether the cipher-text should be raw. + Boolean. If set to TRUE, then Base64 encoding and + decoding will not be performed and HMAC will not + be a hexadecimal string. +============= =============== ============================= ====================================================== + +.. important:: ``encrypt()`` and ``decrypt()`` will return FALSE if + a mandatory parameter is not provided or if a provided + 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 +---------------------------------------- + +For HMAC message authentication, the Encryption library supports +usage of the SHA-2 family of algorithms: + +=========== ==================== ============================ +Algorithm Raw length (bytes) Hex-encoded length (bytes) +=========== ==================== ============================ +sha512 64 128 +sha384 48 96 +sha256 32 64 +sha224 28 56 +=========== ==================== ============================ + +The reason for not including other popular algorithms, such as +MD5 or SHA1 is that they are no longer considered secure enough +and as such, we don't want to encourage their usage. +If you absolutely need to use them, it is easy to do so via PHP's +native `hash_hmac() <http://php.net/hash_hmac()>`_ function. + +Stronger algorithms of course will be added in the future as they +appear and become widely available. + +*************** +Class Reference +*************** + +.. class:: CI_Encryption + + .. method:: initialize($params) + + :param array $params: Configuration parameters + :returns: CI_Encryption instance (method chaining) + :rtype: CI_Encryption + + Initializes (configures) the library to use a different + driver, cipher, mode or key. + + Example:: + + $this->encryption->initialize( + array('mode' => 'ctr') + ); + + Please refer to the :ref:`configuration` section for detailed info. + + .. method:: encrypt($data[, $params = NULL]) + + :param string $data: Data to encrypt + :param array $params: Optional parameters + :returns: Encrypted data or FALSE on failure + :rtype: string + + Encrypts the input data and returns its ciphertext. + + Example:: + + $ciphertext = $this->encryption->encrypt('My secret message'); + + Please refer to the :ref:`custom-parameters` section for information + on the optional parameters. + + .. method:: decrypt($data[, $params = NULL]) + + :param string $data: Data to decrypt + :param array $params: Optional parameters + :returns: Decrypted data or FALSE on failure + :rtype: string + + Decrypts the input data and returns it in plain-text. + + Example:: + + echo $this->encryption->decrypt($ciphertext); + + Please refer to the :ref:`custom-parameters` secrion for information + on the optional parameters. + + .. method:: hkdf($key[, $digest = 'sha512'[, $salt = NULL[, $length = NULL[, $info = '']]]]) + + :param string $key: Input key material + :param string $digest: A SHA-2 family digest algorithm + :param string $salt: Optional salt + :param int $length: Optional output length + :param string $info: Optional context/application-specific info + :returns: A pseudo-random key or FALSE on failure + + Derives a key from another, presumably weaker key. + + This method is used internally to derive an encryption and HMAC key + from your configured *encryption_key*. + + It is publicly available due to its otherwise general purpose. It is + described in `RFC 5869 <https://tools.ietf.org/rfc/rfc5869.txt>`_. + + However, as opposed to the description in RFC 5869, this implementation + doesn't support SHA1. + + Example:: + + $hmac_key = $this->encryption->hkdf( + $key, + 'sha512', + NULL, + NULL, + 'authentication' + ); + + // $hmac_key is a pseudo-random key with a length of 64 bytes
\ No newline at end of file |