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/changelog.rst | 17 ++- user_guide_src/source/installation/upgrade_200.rst | 6 +- user_guide_src/source/installation/upgrade_300.rst | 19 ++- user_guide_src/source/libraries/encrypt.rst | 164 +++++++++++++++++++++ user_guide_src/source/libraries/encryption.rst | 164 --------------------- 5 files changed, 195 insertions(+), 175 deletions(-) create mode 100644 user_guide_src/source/libraries/encrypt.rst delete mode 100644 user_guide_src/source/libraries/encryption.rst (limited to 'user_guide_src') diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst index 3124dea60..5f45f428d 100644 --- a/user_guide_src/source/changelog.rst +++ b/user_guide_src/source/changelog.rst @@ -257,6 +257,14 @@ Release Date: Not Released - Libraries + - Added a new :doc:`Encryption Library ` to replace the old, largely insecure :doc:`Encrypt Library `. + + - :doc:`Encrypt Library ` changes include: + + - Deprecated the library in favor of the new :doc:`Encryption Library `. + - Added support for hashing algorithms other than SHA1 and MD5. + - Removed previously deprecated ``sha1()`` method. + - :doc:`Session Library ` changes include: - Library changed to :doc:`Driver ` with classic 'cookie' driver as the default. @@ -358,11 +366,6 @@ Release Date: Not Released - Added $config['reuse_query_string'] to allow automatic repopulation of query string arguments, combined with normal URI segments. - Removed the default `` `` from a number of the configuration variables. - - :doc:`Encryption Library ` changes include: - - - Added support for hashing algorithms other than SHA1 and MD5. - - Removed previously deprecated ``sha1()`` method. - - :doc:`Profiler Library ` changes include: - Database object names are now being displayed. @@ -574,7 +577,7 @@ Bug fixes for 3.0 - Fixed a bug (#1264) - :doc:`Database Forge ` and :doc:`Database Utilities ` didn't update/reset the databases and tables list cache when a table or a database is created, dropped or renamed. - Fixed a bug (#7) - :doc:`Query Builder `'s ``join()`` method only escaped one set of conditions. - Fixed a bug (#1321) - Core Exceptions class couldn't find the errors/ folder in some cases. -- Fixed a bug (#1202) - :doc:`Encryption Library ` encode_from_legacy() didn't set back the encrypt mode on failure. +- Fixed a bug (#1202) - :doc:`Encrypt Library ` method ``encode_from_legacy()`` didn't set back the encrypt mode on failure. - Fixed a bug (#145) - compile_binds() failed when the bind marker was present in a literal string within the query. - Fixed a bug in protect_identifiers() where if passed along with the field names, operators got escaped as well. - Fixed a bug (#10) - :doc:`URI Library ` internal method _detect_uri() failed with paths containing a colon. @@ -1289,7 +1292,7 @@ Hg Tag: v2.0.0 - Documented append_output() in the :doc:`Output Class `. - Documented a second argument in the decode() function for the - :doc:`Encryption Class `. + :doc:`Encryption Class `. - Documented db->close(). - Updated the router to support a default route with any number of segments. diff --git a/user_guide_src/source/installation/upgrade_200.rst b/user_guide_src/source/installation/upgrade_200.rst index 29f44bd9e..948b1bc58 100644 --- a/user_guide_src/source/installation/upgrade_200.rst +++ b/user_guide_src/source/installation/upgrade_200.rst @@ -50,11 +50,11 @@ to :: Step 4: Update stored encrypted data ==================================== -.. note:: If your application does not use the Encryption library, does +.. note:: If your application does not use the Encrypt library, does not store Encrypted data permanently, or is on an environment that does not support Mcrypt, you may skip this step. -The Encryption library has had a number of improvements, some for +The Encrypt library has had a number of improvements, some for encryption strength and some for performance, that has an unavoidable consequence of making it no longer possible to decode encrypted data produced by the original version of this library. To help with the @@ -65,7 +65,7 @@ replace stale encrypted data with fresh in your applications, either on the fly or en masse. Please read `how to use this -method <../libraries/encryption.html#legacy>`_ in the Encryption library +method <../libraries/encrypt.html#legacy>`_ in the Encrypt library documentation. Step 5: Remove loading calls for the compatibility helper. diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst index 88bb11178..94385978e 100644 --- a/user_guide_src/source/installation/upgrade_300.rst +++ b/user_guide_src/source/installation/upgrade_300.rst @@ -318,7 +318,7 @@ The SHA1 library The previously deprecated SHA1 library has been removed, alter your code to use PHP's native ``sha1()`` function to generate a SHA1 hash. -Additionally, the ``sha1()`` method in the :doc:`Encryption Library <../libraries/encryption>` has been removed. +Additionally, the ``sha1()`` method in the :doc:`Encrypt Library <../libraries/encrypt>` has been removed. The EXT constant ================ @@ -333,6 +333,23 @@ Smiley helper js_insert_smiley() :doc:`Smiley Helper <../helpers/smiley_helper>` function ``js_insert_smiley()`` has been deprecated since CodeIgniter 1.7.2 and is now removed. You'll need to switch to ``smiley_js()`` instead. +The Encrypt library +=================== + +Following numerous vulnerability reports, the :doc:`Encrypt Library <../libraries/encrypt>` has +been deprecated and a new, :doc:`Encryption Library <../libraries/encryption>` is added to take +its place. + +The new library requires either the `MCrypt extension `_ or PHP 5.3.3 and +the `OpenSSL extension `_. While this might be rather inconvenient, it is +a requirement that allows us to have properly implemented cryptographic functions. + +.. note:: The :doc:`Encrypt Library <../libraries/encrypt>` is still available for the purpose + of keeping backwards compatibility. + +.. important:: You are strongly encouraged to switch to the new :doc:`Encryption Library + <../libraries/encryption>` as soon as possible! + Database drivers 'mysql', 'sqlite', 'mssql', 'pdo/dblib' ======================================================== diff --git a/user_guide_src/source/libraries/encrypt.rst b/user_guide_src/source/libraries/encrypt.rst new file mode 100644 index 000000000..a38122203 --- /dev/null +++ b/user_guide_src/source/libraries/encrypt.rst @@ -0,0 +1,164 @@ +################ +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 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