diff options
Diffstat (limited to 'user_guide_src/source/libraries/encryption.rst')
| -rw-r--r-- | user_guide_src/source/libraries/encryption.rst | 28 |
1 files changed, 27 insertions, 1 deletions
diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index d445bf42f..599be4df0 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -2,6 +2,11 @@ Encryption Library ################## +.. 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 + <http://php.net/password>`_. + The Encryption Library provides two-way data encryption. To do so in a cryptographically secure way, it utilizes PHP extensions that are unfortunately not always available on all systems. @@ -106,6 +111,18 @@ and set:: $config['encryption_key'] = 'YOUR KEY'; +You'll notice that the ``create_key()`` method outputs binary data, which +is hard to deal with (i.e. a copy-paste may damage it), so you may use +``bin2hex()``, ``hex2bin()`` or Base64-encoding to work with the key in +a more friendly manner. For example:: + + // Get a hex-encoded representation of the key: + $key = bin2hex($this->encryption->create_key(16)); + + // Put the same value in your config with hex2bin(), + // so that it is still passed as binary to the library: + $config['encryption_key'] = hex2bin(<your hex-encoded key>); + .. _ciphers-and-modes: Supported encryption ciphers and modes @@ -465,7 +482,7 @@ The reason for not including other popular algorithms, such as MD5 or SHA1 is that they are no longer considered secure enough and as such, we don't want to encourage their usage. If you absolutely need to use them, it is easy to do so via PHP's -native `hash_hmac() <http://php.net/hash_hmac()>`_ function. +native `hash_hmac() <http://php.net/manual/en/function.hash-hmac.php>`_ function. Stronger algorithms of course will be added in the future as they appear and become widely available. @@ -525,6 +542,15 @@ Class Reference Please refer to the :ref:`custom-parameters` secrion for information on the optional parameters. + .. php:method:: create_key($length) + + :param int $length: Output length + :returns: A pseudo-random cryptographic key with the specified length, or FALSE on failure + :rtype: string + + Creates a cryptographic key by fetching random data from + the operating system's sources (i.e. /dev/urandom). + .. php:method:: hkdf($key[, $digest = 'sha512'[, $salt = NULL[, $length = NULL[, $info = '']]]]) :param string $key: Input key material |