diff options
Diffstat (limited to 'user_guide_src/source/libraries/encryption.rst')
| -rw-r--r-- | user_guide_src/source/libraries/encryption.rst | 585 |
1 files changed, 0 insertions, 585 deletions
diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst deleted file mode 100644 index b16511d4d..000000000 --- a/user_guide_src/source/libraries/encryption.rst +++ /dev/null @@ -1,585 +0,0 @@ -################## -Encryption Library -################## - -.. important:: DO NOT use this or any other *encryption* library for - user password storage! Passwords must be *hashed* instead, and you - should do that via PHP's own `Password Hashing extension - <http://php.net/password>`_. - -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 dependencies in order to use this -library: - -- `OpenSSL <http://php.net/openssl>`_ -- `MCrypt <http://php.net/mcrypt>`_ (and `MCRYPT_DEV_URANDOM` availability) - -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. - -.. 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('encryption'); - -Once loaded, the Encryption library object will be available using:: - - $this->encryption - -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 lose access to the 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 **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. - -To save your key to your *application/config/config.php*, open the file -and set:: - - $config['encryption_key'] = 'YOUR KEY'; - -You'll notice that the ``create_key()`` method outputs binary data, which -is hard to deal with (i.e. a copy-paste may damage it), so you may use -``bin2hex()``, ``hex2bin()`` or Base64-encoding to work with the key in -a more friendly manner. For example:: - - // Get a hex-encoded representation of the key: - $key = bin2hex($this->encryption->create_key(16)); - - // Put the same value in your config with hex2bin(), - // so that it is still passed as binary to the library: - $config['encryption_key'] = hex2bin(<your hex-encoded 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 88-128 / 11-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, 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 -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-128 MCrypt 40-128 / 5-16 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:: CAST-128 / CAST-5 is also listed in both the portable and - driver-specific ciphers list. This is because OpenSSL's - implementation doesn't appear to be working correctly with - key sizes of 80 bits and lower. - -.. 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). -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 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 against 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. -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. - -.. _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/manual/en/function.hash-hmac.php>`_ function. - -Stronger algorithms of course will be added in the future as they -appear and become widely available. - -*************** -Class Reference -*************** - -.. php:class:: CI_Encryption - - .. php: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. - - .. php: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. - - .. php: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. - - .. php:method:: create_key($length) - - :param int $length: Output length - :returns: A pseudo-random cryptographic key with the specified length, or FALSE on failure - :rtype: string - - Creates a cryptographic key by fetching random data from - the operating system's sources (i.e. /dev/urandom). - - .. php: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 - :rtype: string - - 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 |