summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/encryption.rst
diff options
context:
space:
mode:
authorAhmad Anbar <aanbar@gmail.com>2015-04-06 18:59:53 +0200
committerAhmad Anbar <aanbar@gmail.com>2015-04-06 18:59:53 +0200
commit5e50c42ef27261bc7fcb279499ce76cfc2519aa6 (patch)
treed74d660534b72ddc0b6cda9147cecfb64a225346 /user_guide_src/source/libraries/encryption.rst
parented520408514fff6486788e1543589418d24d885e (diff)
parent7726b75552f765af94038e47a4a4272ac08c646e (diff)
Merge remote-tracking branch 'upstream/develop' into develop
Diffstat (limited to 'user_guide_src/source/libraries/encryption.rst')
-rw-r--r--user_guide_src/source/libraries/encryption.rst28
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