summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDerek Jones <derek.jones@ellislab.com>2013-07-25 02:44:29 +0200
committerDerek Jones <derek.jones@ellislab.com>2013-07-25 02:44:29 +0200
commit5d80d0f215a48ed985e0e4ff9eb50f53f399e9bd (patch)
tree07d6444b90f755fed482312dd04951a9073a35f0
parentd386f25b4288bbe706c662ec169627d9e91ed31f (diff)
Update Encrypt lib docs
-rw-r--r--user_guide_src/source/libraries/encryption.rst176
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