diff options
Diffstat (limited to 'user_guide_src/source/libraries/encryption.rst')
| -rw-r--r-- | user_guide_src/source/libraries/encryption.rst | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst new file mode 100644 index 000000000..27c6a6484 --- /dev/null +++ b/user_guide_src/source/libraries/encryption.rst @@ -0,0 +1,173 @@ +################ +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 (128 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 <http://php.net/mcrypt>`_. + +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 <http://php.net/mcrypt>`_. + +$this->encrypt->sha1(); +======================= + +SHA1 encoding function. Provide a string and it will return a 160 bit +one way hash. Note: SHA1, just like MD5 is non-decodable. Example:: + + $hash = $this->encrypt->sha1('Some string'); + +Many PHP installations have SHA1 support by default so if all you need +is to encode a hash it's simpler to use the native function:: + + $hash = sha1('Some string'); + +If your server does not support SHA1 you can use the provided function. + +$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. + +**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. |