diff options
Diffstat (limited to 'user_guide_src/source/libraries/encryption.rst')
| -rw-r--r-- | user_guide_src/source/libraries/encryption.rst | 176 |
1 files changed, 105 insertions, 71 deletions
diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index a38122203..f7235bfd2 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -10,6 +10,17 @@ 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. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +**************************** +Using the Encryption Library +**************************** + Setting your Key ================ @@ -61,104 +72,127 @@ 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 +Once loaded, the Encrypt library object will be available using +``$this->encrypt`` + +*************** +Class Reference +*************** + +.. class:: CI_Encrypt + + .. method:: encode($string, $key = '') + + :param string $string: contents to be encrypted + :param string $key: encryption key + :returns: string + + 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->encode() -======================== + .. method:: decode($string, $key = '') -Performs the data encryption and returns it as a string. Example:: + :param string $string: contents to be decrypted + :param string $key: encryption key + :returns: string - $msg = 'My secret message'; + Decrypts an encoded string. Example:: - $encrypted_string = $this->encrypt->encode($msg); - + $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84'; -You can optionally pass your encryption key via the second parameter if -you don't want to use the one in your config file:: + $plaintext_string = $this->encrypt->decode($encrypted_string); - $msg = 'My secret message'; - $key = 'super-secret-key'; + You can optionally pass your encryption key via the second parameter if + you don't want to use the one in your config file:: - $encrypted_string = $this->encrypt->encode($msg, $key); + $msg = 'My secret message'; + $key = 'super-secret-key'; -$this->encrypt->decode() -======================== + $encrypted_string = $this->encrypt->decode($msg, $key); -Decrypts an encoded string. Example:: - $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84'; + .. method:: set_cipher($cipher) - $plaintext_string = $this->encrypt->decode($encrypted_string); + :param int $cipher: valid PHP Mcrypt cypher constant + :returns: CI_Encrypt object for method chaining -You can optionally pass your encryption key via the second parameter if -you don't want to use the one in your config file:: + Permits you to set an Mcrypt cipher. By default it uses + **MCRYPT_RIJNDAEL_256**. Example:: - $msg = 'My secret message'; - $key = 'super-secret-key'; + $this->encrypt->set_cipher(MCRYPT_BLOWFISH); - $encrypted_string = $this->encrypt->decode($msg, $key); + Please visit php.net for a list of `available + ciphers <http://php.net/mcrypt>`_. -$this->encrypt->set_cipher(); -============================== + If you'd like to manually test whether your server supports Mcrypt you + can use:: -Permits you to set an Mcrypt cipher. By default it uses -**MCRYPT_RIJNDAEL_256**. Example:: + echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; - $this->encrypt->set_cipher(MCRYPT_BLOWFISH); -Please visit php.net for a list of `available -ciphers <http://php.net/mcrypt>`_. + .. method:: set_mode($mode) -If you'd like to manually test whether your server supports Mcrypt you -can use:: + :param int $mode: valid PHP Mcrypt mode constant + :returns: CI_Encrypt object for method chaining - echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; + Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. + Example:: -$this->encrypt->set_mode(); -============================ + $this->encrypt->set_mode(MCRYPT_MODE_CFB); -Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. -Example:: + Please visit php.net for a list of `available + modes <http://php.net/mcrypt>`_. - $this->encrypt->set_mode(MCRYPT_MODE_CFB); -Please visit php.net for a list of `available -modes <http://php.net/mcrypt>`_. + .. method:: encode_from_legacy($string[, $legacy_mode = MCRYPT_MODE_ECB[, $key = '']]) -$this->encrypt->encode_from_legacy($orig_data, $legacy_mode = MCRYPT_MODE_ECB, $key = ''); -========================================================================================== + :param string $string: contents to be encrypted + :param int $legacy_mode: valid PHP Mcrypt cypher constant + :param string $key: encryption key + :returns: string -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. + 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. + .. 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); + $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 + ====================== =============== ======================================================================= + 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 |