From 5d80d0f215a48ed985e0e4ff9eb50f53f399e9bd Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 24 Jul 2013 17:44:29 -0700 Subject: Update Encrypt lib docs --- user_guide_src/source/libraries/encryption.rst | 176 +++++++++++++++---------- 1 file changed, 105 insertions(+), 71 deletions(-) (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 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 + +
+ +**************************** +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 `_. -$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 `_. + .. 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 `_. - $this->encrypt->set_mode(MCRYPT_MODE_CFB); -Please visit php.net for a list of `available -modes `_. + .. 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 -- cgit v1.2.3-24-g4f1b From 28c2c975b118016d07212ed8e7c22ff280309f82 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 04:27:48 +0200 Subject: [ci skip] Add return types to library docs --- user_guide_src/source/libraries/encryption.rst | 53 +++++++++++++------------- 1 file changed, 26 insertions(+), 27 deletions(-) (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 index f7235bfd2..567a1e990 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -81,11 +81,12 @@ Class Reference .. class:: CI_Encrypt - .. method:: encode($string, $key = '') + .. method:: encode($string[, $key = '']) - :param string $string: contents to be encrypted - :param string $key: encryption key - :returns: string + :param string $string: Data to encrypt + :param string $key: Encryption key + :returns: Encrypted string + :rtype: string Performs the data encryption and returns it as a string. Example:: @@ -101,12 +102,12 @@ Class Reference $encrypted_string = $this->encrypt->encode($msg, $key); + .. method:: decode($string[, $key = '']) - .. method:: decode($string, $key = '') - - :param string $string: contents to be decrypted - :param string $key: encryption key - :returns: string + :param string $string: String to decrypt + :param string $key: Encryption key + :returns: Plain-text string + :rtype: string Decrypts an encoded string. Example:: @@ -122,46 +123,44 @@ Class Reference $encrypted_string = $this->encrypt->decode($msg, $key); - .. method:: set_cipher($cipher) - :param int $cipher: valid PHP Mcrypt cypher constant - :returns: CI_Encrypt object for method chaining + :param int $cipher: Valid PHP MCrypt cypher constant + :returns: CI_Encrypt instance (method chaining) + :rtype: CI_Encrypt Permits you to set an Mcrypt cipher. By default it uses - **MCRYPT_RIJNDAEL_256**. Example:: + ``MCRYPT_RIJNDAEL_256``. Example:: $this->encrypt->set_cipher(MCRYPT_BLOWFISH); - Please visit php.net for a list of `available - ciphers `_. + Please visit php.net for a list of `available ciphers `_. - If you'd like to manually test whether your server supports Mcrypt you + If you'd like to manually test whether your server supports MCrypt you can use:: - echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; - + echo extension_loaded('mcrypt') ? 'Yup' : 'Nope'; .. method:: set_mode($mode) - :param int $mode: valid PHP Mcrypt mode constant - :returns: CI_Encrypt object for method chaining + :param int $mode: Valid PHP MCrypt mode constant + :returns: CI_Encrypt instance (method chaining) + :rtype: CI_Encrypt 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 `_. - + Please visit php.net for a list of `available modes `_. .. method:: encode_from_legacy($string[, $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 + :param string $string: String to encrypt + :param int $legacy_mode: Valid PHP MCrypt cipher constant + :param string $key: Encryption key + :returns: Newly encrypted string + :rtype: string Enables you to re-encode data that was originally encrypted with CodeIgniter 1.x to be compatible with the Encryption library in -- cgit v1.2.3-24-g4f1b