From 4a2918a33c756ac7cc9defc2e6acd371e4412af6 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Wed, 5 Feb 2014 01:03:46 +0200 Subject: Integrate CI_Encryption into the framework TODO: Add documentation in user_guide_src/source/libraries/encryption.rst --- user_guide_src/source/libraries/encryption.rst | 164 ------------------------- 1 file changed, 164 deletions(-) delete mode 100644 user_guide_src/source/libraries/encryption.rst (limited to 'user_guide_src/source/libraries/encryption.rst') diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst deleted file mode 100644 index a38122203..000000000 --- a/user_guide_src/source/libraries/encryption.rst +++ /dev/null @@ -1,164 +0,0 @@ -################ -Encryption Class -################ - -The Encryption Class provides two-way data encryption. It uses a scheme -that either compiles the message using a randomly hashed bitwise XOR -encoding scheme, or is encrypted using the Mcrypt library. If Mcrypt is -not available on your server the encoded message will still provide a -reasonable degree of security for encrypted sessions or other such -"light" purposes. If Mcrypt is available, you'll be provided with a high -degree of security appropriate for storage. - -Setting your Key -================ - -A *key* is a piece of information that controls the cryptographic -process and permits an encrypted string to be decoded. In fact, the key -you chose will provide the **only** means to decode data that was -encrypted with that key, so not only must you choose the key carefully, -you must never change it if you intend use it for persistent data. - -It goes without saying that you should guard your key carefully. Should -someone gain access to your key, the data will be easily decoded. 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. - -To take maximum advantage of the encryption algorithm, your key should -be 32 characters in length (256 bits). The key should be as random a -string as you can concoct, with numbers and uppercase and lowercase -letters. Your key should **not** be a simple text string. In order to be -cryptographically secure it needs to be as random as possible. - -Your 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 encoding/decoding. - -To save your key to your **application/config/config.php**, open the file -and set:: - - $config['encryption_key'] = "YOUR KEY"; - -Message Length -============== - -It's important for you to know that the encoded messages the encryption -function generates will be approximately 2.6 times longer than the -original message. For example, if you encrypt the string "my super -secret data", which is 21 characters in length, you'll end up with an -encoded string that is roughly 55 characters (we say "roughly" because -the encoded string length increments in 64 bit clusters, so it's not -exactly linear). Keep this information in mind when selecting your data -storage mechanism. Cookies, for example, can only hold 4K of -information. - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the Encryption class is -initialized in your controller using the **$this->load->library** function:: - - $this->load->library('encrypt'); - -Once loaded, the Encrypt library object will be available using: -$this->encrypt - -$this->encrypt->encode() -======================== - -Performs the data encryption and returns it as a string. Example:: - - $msg = 'My secret message'; - - $encrypted_string = $this->encrypt->encode($msg); - - -You can optionally pass your encryption key via the second parameter if -you don't want to use the one in your config file:: - - $msg = 'My secret message'; - $key = 'super-secret-key'; - - $encrypted_string = $this->encrypt->encode($msg, $key); - -$this->encrypt->decode() -======================== - -Decrypts an encoded string. Example:: - - $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84'; - - $plaintext_string = $this->encrypt->decode($encrypted_string); - -You can optionally pass your encryption key via the second parameter if -you don't want to use the one in your config file:: - - $msg = 'My secret message'; - $key = 'super-secret-key'; - - $encrypted_string = $this->encrypt->decode($msg, $key); - -$this->encrypt->set_cipher(); -============================== - -Permits you to set an Mcrypt cipher. By default it uses -**MCRYPT_RIJNDAEL_256**. Example:: - - $this->encrypt->set_cipher(MCRYPT_BLOWFISH); - -Please visit php.net for a list of `available -ciphers `_. - -If you'd like to manually test whether your server supports Mcrypt you -can use:: - - echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; - -$this->encrypt->set_mode(); -============================ - -Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. -Example:: - - $this->encrypt->set_mode(MCRYPT_MODE_CFB); - -Please visit php.net for a list of `available -modes `_. - -$this->encrypt->encode_from_legacy($orig_data, $legacy_mode = MCRYPT_MODE_ECB, $key = ''); -========================================================================================== - -Enables you to re-encode data that was originally encrypted with -CodeIgniter 1.x to be compatible with the Encryption library in -CodeIgniter 2.x. It is only necessary to use this method if you have -encrypted data stored permanently such as in a file or database and are -on a server that supports Mcrypt. "Light" use encryption such as -encrypted session data or transitory encrypted flashdata require no -intervention on your part. However, existing encrypted Sessions will be -destroyed since data encrypted prior to 2.x will not be decoded. - -.. important:: - **Why only a method to re-encode the data instead of maintaining legacy - methods for both encoding and decoding?** The algorithms in the - Encryption library have improved in CodeIgniter 2.x both for performance - and security, and we do not wish to encourage continued use of the older - methods. You can of course extend the Encryption library if you wish and - replace the new methods with the old and retain seamless compatibility - with CodeIgniter 1.x encrypted data, but this a decision that a - developer should make cautiously and deliberately, if at all. - -:: - - $new_data = $this->encrypt->encode_from_legacy($old_encrypted_string); - -====================== =============== ======================================================================= -Parameter Default Description -====================== =============== ======================================================================= -**$orig_data** n/a The original encrypted data from CodeIgniter 1.x's Encryption library -**$legacy_mode** MCRYPT_MODE_ECB The Mcrypt mode that was used to generate the original encrypted data. - CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will assume that - to be the case unless overridden by this parameter. -**$key** n/a The encryption key. This it typically specified in your config file as - outlined above. -====================== =============== ======================================================================= \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 4b450651ed3b9413be0245401da706c218850f53 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 10 Feb 2014 06:59:54 +0200 Subject: CI_Encryption: Rename 'base64' parameter to 'raw_data' and add docs --- user_guide_src/source/libraries/encryption.rst | 555 +++++++++++++++++++++++++ 1 file changed, 555 insertions(+) create mode 100644 user_guide_src/source/libraries/encryption.rst (limited to 'user_guide_src/source/libraries/encryption.rst') 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 `_ (and PHP 5.3.3) +- `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 + +
+ +**************************** +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 +`_ (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 + `_. + +.. 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 `, 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' => '' + ) + ); + +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() `_ 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 `_. + + 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 -- cgit v1.2.3-24-g4f1b