diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index 335d9be1771c..a05d4361eca7 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -3,33 +3,32 @@ Encryption Service ################## .. important:: DO NOT use this or any other *encryption* library for - user password storage! Passwords must be *hashed* instead, and you - should do that via PHP's own `Password Hashing extension + password storage! Passwords must be *hashed* instead, and you + should do that through PHP's `Password Hashing extension `_. The Encryption Service provides two-way symmetric (secret key) data encryption. -The encryption manager will instantiate and/or initialize an -encryption handler to suit your parameters, explained below. +The service will instantiate and/or initialize an +encryption **handler** to suit your parameters as explained below. -The handlers adapt our simple ``EncrypterInterface`` to use an -appropriate PHP cryptographic extension or third party library. -Such extensions may need to be explicitly enabled in your instance of PHP. +Encryption Service handlers must implement CodeIgniter's simple ``EncrypterInterface``. +Using an appropriate PHP cryptographic extension or third-party library may require +additional software is installed on your server and/or might need to be explicitly +enabled in your instance of PHP. -The following extensions are currently supported: +The following PHP extensions are currently supported: - `OpenSSL `_ +This is not a full cryptographic solution. If you need more capabilities, for example, +public-key encryption, we suggest you consider direct use of OpenSSL or +one of the other `Cryptography Extensions `_. +A more comprehensive package like `Halite `_ +(an O-O package built on libsodium) is another possibility. + .. note:: Support for the ``MCrypt`` extension has been dropped, as that has been deprecated as of PHP 7.2. -This is not a full cryptographic solution. If you need more capabilities, -for instance public key encryption, we suggest you consider using the -above extensions directly, or look into some of the more comprehensive -packages, like: - -- `Halite `_, an O-O package built on libsodium, or -- `Sodium_compat `_, a pure PHP implementation that adds libsodium support to earlier versions of PHP (5.2.4+) - .. contents:: :local: @@ -37,6 +36,8 @@ packages, like:
+.. _usage: + **************************** Using the Encryption Library **************************** @@ -45,12 +46,12 @@ Like all services in CodeIgniter, it can be loaded via ``Config\Services``:: $encrypter = \Config\Services::encrypter(); -Assuming you have set your starting key (see below), -encrypting and decrypting data is simple - pass the appropriate string to the -``encrypt()`` and/or ``decrypt()`` methods:: +Assuming you have set your starting key (see :ref:`configuration`), +encrypting and decrypting data is simple - pass the appropriate string to ``encrypt()`` +and/or ``decrypt()`` methods:: - $plain_text = 'This is a plain-text message!'; - $ciphertext = $encrypter->encrypt($plaintext); + $plainText = 'This is a plain-text message!'; + $ciphertext = $encrypter->encrypt($plainText); // Outputs: This is a plain-text message! echo $encrypter->decrypt($ciphertext); @@ -61,61 +62,60 @@ You don't need to worry about it. .. _configuration: -Configuring the library +Configuring the Library ======================= -The example above uses the default configuration settings, -found in ``application/config/Encryption.php``. +The example above uses the configuration settings found in ``app/Config/Encryption.php``. There are only two settings: ======== =============================================== Option Possible values (default in parentheses) ======== =============================================== -driver Preferred handler (OpenSSL) key Encryption key starter +driver Preferred handler (OpenSSL) ======== =============================================== -You can over-ride any of these settings by passing your own ``Config`` object -to the Services:: +You can replace the config file's settings by passing a configuration +object of your own to the ``Services`` call. The ``$config`` variable must be +an instance of either the `Config\\Encryption` class or an object +that extends `CodeIgniter\\Config\\BaseConfig`. +:: + + $config = new Config\Encryption(); + $config->key = 'aBigsecret_ofAtleast32Characters'; + $config->driver = 'OpenSSL'; $encrypter = \Config\Services::encrypter($config); -Default behavior -================ -By default, the Encryption Library will use the OpenSSL handler, with -the AES-256-CTR cipher, -using your configured *key* and SHA512 HMAC authentication. +Default Behavior +================ -The *key* you provide is used to derive -two separate keys from your configured one: -one for encryption and one for authentication. This is -done via a technique called `HMAC-based Key Derivation Function -`_ (HKDF). +By default, the Encryption Library uses the OpenSSL handler. That handler encrypts using +the AES-256-CTR algorithm, your configured *key*, and SHA512 HMAC authentication. -Setting your encryption key +Setting Your Encryption Key =========================== -Your encryption key **must** be as long as the encryption algorithm in use -allows. For AES-256, that's 256 bits or 32 bytes (characters) long. +Your encryption key **must** be as long as the encryption algorithm in use allows. +For AES-256, that's 256 bits or 32 bytes (characters) long. -The key should be as random as possible and it **must not** be a regular -text string, nor the output of a hashing function, etc. In order to create -a proper key, you can use the Encryption library's ``createKey()`` method +The key should be as random as possible, and it **must not** be a regular text string, +nor the output of a hashing function, etc. To create a proper key, +you can use the Encryption library's ``createKey()`` method. :: // $key will be assigned a 32-byte (256-bit) random key $key = Encryption::createKey(32); -The key can be either stored in your *application/Config/Encryption.php*, or -you can design your own storage mechanism and pass the key dynamically -when encrypting/decrypting. +The key can be stored in *app/Config/Encryption.php*, or you can design +a storage mechanism of your own and pass the key dynamically when encrypting/decrypting. -To save your key to your *application/Config/Encryption.php*, open the file +To save your key to your *app/Config/Encryption.php*, open the file and set:: - $key = 'YOUR KEY'; + public $key = 'YOUR KEY'; Encoding Keys or Results ------------------------ @@ -126,7 +126,7 @@ is hard to deal with (i.e. a copy-paste may damage it), so you may use a more friendly manner. For example:: // Get a hex-encoded representation of the key: - $encoded = bin2hex($encrypter->createKey(32)); + $encoded = bin2hex(Encryption::createKey(32)); // Put the same value in your config with hex2bin(), // so that it is still passed as binary to the library: @@ -144,36 +144,43 @@ Encryption Handler Notes OpenSSL Notes ------------- -OpenSSL has been a standard part of PHP for some time. +The `OpenSSL `_ extension has been a standard part of PHP for a long time. + +CodeIgniter's OpenSSL handler uses the AES-256-CTR cipher. -The OpenSSL handler uses the AES-256-CTR cipher. +The *key* your configuration provides is used to derive two other keys, one for +encryption and one for authentication. This is achieved by way of a technique known +as an `HMAC-based Key Derivation Function `_ (HKDF). Message Length ============== -An encrypted string is usually -longer than the original, plain-text string (depending on the cipher). +An encrypted string is usually longer than the original, plain-text string (depending on the cipher). This is influenced by the cipher algorithm itself, the initialization vector (IV) -prepended to the -cipher-text and the HMAC authentication message that is also prepended. +prepended to the cipher-text, and the HMAC authentication message that is also prepended. Furthermore, the encrypted message is also Base64-encoded so that it is safe -for storage and transmission, regardless of a possible character set in use. +for storage and transmission regardless of the character-set in use. Keep this information in mind when selecting your data storage mechanism. Cookies, for example, can only hold 4K of information. -Using the Encryption manager directly +Using the Encryption Service Directly ===================================== -Instead of, or in addition to, using the `Services` described -at the beginning of this page, you can use the encryption manager -directly, to create an ``Encrypter`` or to change the settings -of the current one:: +Instead of (or in addition to) using ``Services`` as described in :ref:`usage`, +you can create an "Encrypter" directly, or change the settings of an existing instance. +:: + // create an Encrypter instance $encryption = new \Encryption\Encryption(); + + // reconfigure an instance with different settings $encrypter = $encryption->initialize($config); +Remember, that ``$config`` must me an instance of either a `Config\Encryption` class +or an object that extends `CodeIgniter\Config\BaseConfig`. + *************** Class Reference