Permalink
Browse files

Update docs for bcrypt addition.

  • Loading branch information...
1 parent d96e76e commit 27b7cb3722645581a659211ca23f4d35a34ab823 @markstory markstory committed Jul 23, 2012
Showing with 44 additions and 6 deletions.
  1. +10 −0 en/appendices/2-3-migration-guide.rst
  2. +34 −6 en/core-utility-libraries/security.rst
@@ -60,3 +60,13 @@ Testing
it by adding ``core.cake_sessions`` to your fixture list.
+Utility
+=======
+
+Security
+--------
+
+- Support for `bcrypt <http://codahale.com/how-to-safely-store-a-password/>`_
+ was added. See the :php:class:`Security::hash()` documentation for more
+ information on how to use bcrypt.
+
@@ -43,6 +43,11 @@ Security API
// Later decrypt it.
$decrypted = Security::rijndael($encrypted, Configure::read('Security.key'), 'decrypt');
+ ``rijndael()`` can be used to store data you need to decrypt later, like the
+ contents of cookies. It should **never** be used to store passwords.
+ Instead you should use the one way hashing methods provided by
+ :php:method:`~Security::hash()`
+
.. versionadded:: 2.2
``Security::rijndael()`` was added in 2.2.
@@ -65,20 +70,43 @@ Security API
Create a hash from string using given method. Fallback on next
available method. If ``$salt`` is set to true, the applications salt
- value will be used.
-
- ::
+ value will be used::
<?php
- //Using the application's salt value
+ // Using the application's salt value
$sha1 = Security::hash('CakePHP Framework', 'sha1', true);
- //Using a custom salt value
+ // Using a custom salt value
$md5 = Security::hash('CakePHP Framework', 'md5', 'my-salt');
- //Using the default hash algorithm
+ // Using the default hash algorithm
+ $hash = Security::hash('CakePHP Framework');
+
+ ``hash()`` also supports more secure hashing algorithms like bcrypt. When
+ using bcrypt, you should be mindful of the slightly different usage.
+ Creating an initial hash works the same as other algorithms::
+
+ <?php
+ // Create a hash using bcrypt
+ Security::setHash('blowfish');
$hash = Security::hash('CakePHP Framework');
+ Unlike other hash types comparing plain text values to hashed values should
+ be done as follows::
+
+ <?php
+ // $storedPassword, is a previously generated bcrypt hash.
+ $newHash = Security::hash($newPassword, 'blowfish', $storedPassword);
+
+ When comparing values hashed with bcrypt, the original hash should be
+ provided as the ``$salt`` parameter. This allows bcrypt to reuse the same
+ cost and salt values, allowing the generated hash to end up with the same
+ resulting hash given the same input value.
+
+ .. versionchanged:: 2.3
+ Support for bcrypt was added in 2.3
+
+
.. php:staticmethod:: inactiveMins( )
:rtype: integer

0 comments on commit 27b7cb3

Please sign in to comment.