├── Bcrypt.php
├── README.markdown
└── license.txt


/Bcrypt.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | /**
  4 |  * Bcrypt class
  5 |  * 
  6 |  * @author Christian Metz
  7 |  * @since 23.06.2012
  8 |  * @copyright Christian Metz - MetzWeb Networks 2012
  9 |  * @version 1.0
 10 |  * @license BSD http://www.opensource.org/licenses/bsd-license.php
 11 |  */
 12 | 
 13 | class Bcrypt {
 14 | 
 15 |   /**
 16 |    * Work cost factor
 17 |    * range between [04; 31]
 18 |    * 
 19 |    * @var string
 20 |    */
 21 |   private static $_workFactor = 12;
 22 | 
 23 |   /**
 24 |    * Default identifier
 25 |    * 
 26 |    * @var string
 27 |    */
 28 |   private static $_identifier = '2y';
 29 | 
 30 |   /**
 31 |    * All valid hash identifiers
 32 |    * 
 33 |    * @var array
 34 |    */
 35 |   private static $_validIdentifiers = array ('2a', '2x', '2y');
 36 | 
 37 |   /**
 38 |    * Hash password
 39 |    * 
 40 |    * @param string $password
 41 |    * @param integer [optional] $workFactor
 42 |    * @return string
 43 |    */
 44 |   public static function hashPassword($password, $workFactor = 0) {
 45 |     if (version_compare(PHP_VERSION, '5.3') < 0) {
 46 |       throw new Exception('Bcrypt requires PHP 5.3 or above');
 47 |     }
 48 |     
 49 |     $salt = self::_genSalt($workFactor);
 50 |     return crypt($password, $salt);
 51 |   }
 52 | 
 53 |   /**
 54 |    * Check bcrypt password
 55 |    * 
 56 |    * @param string $password
 57 |    * @param string $storedHash
 58 |    * @return boolean
 59 |    */
 60 |   public static function checkPassword($password, $storedHash) {
 61 |     if (version_compare(PHP_VERSION, '5.3') < 0) {
 62 |       throw new Exception('Bcrypt requires PHP 5.3 or above');
 63 |     }
 64 |     
 65 |     self::_validateIdentifier($storedHash);
 66 |     $checkHash = crypt($password, $storedHash);
 67 |     
 68 |     return ($checkHash === $storedHash);
 69 |   }
 70 | 
 71 |   /**
 72 |    * Generates the salt string
 73 |    * 
 74 |    * @param integer $workFactor
 75 |    * @return string
 76 |    */
 77 |   private static function _genSalt($workFactor) {
 78 |     if ($workFactor < 4 || $workFactor > 31) {
 79 |       $workFactor = self::$_workFactor;
 80 |     }
 81 |     
 82 |     $input = self::_getRandomBytes();
 83 |     $salt = '$' . self::$_identifier . '$';
 84 |     
 85 |     $salt .= str_pad($workFactor, 2, '0', STR_PAD_LEFT);
 86 |     $salt .= '$';
 87 |     
 88 |     $salt .= substr(strtr(base64_encode($input), '+', '.'), 0, 22);
 89 |     
 90 |     return $salt;
 91 |   }
 92 | 
 93 |   /**
 94 |    * OpenSSL's random generator
 95 |    * 
 96 |    * @return string
 97 |    */
 98 |   private static function _getRandomBytes() {
 99 |     if (!function_exists('openssl_random_pseudo_bytes')) {
100 |       throw new Exception('Unsupported hash format.');
101 |     }
102 |     return openssl_random_pseudo_bytes(16);
103 |   }
104 | 
105 |   /**
106 |    * Validate identifier
107 |    * 
108 |    * @param string $hash
109 |    * @return void
110 |    */
111 |   private static function _validateIdentifier($hash) {
112 |     if (!in_array(substr($hash, 1, 2), self::$_validIdentifiers)) {
113 |       throw new Exception('Unsupported hash format.');
114 |     }
115 |   }
116 | 
117 | }


--------------------------------------------------------------------------------
/README.markdown:
--------------------------------------------------------------------------------
  1 | # Bcrypt PHP Class #
  2 | 
  3 | ## About ##
  4 | 
  5 | This is an easy-to-use static PHP class for Bcyrpt.  
  6 | Your feedback is always welcome.
  7 | 
  8 | > If you are new to the concept of Bcyrpt, just [take a look](#bcrypt) at it.  
  9 | > The documentation is also available as a [PDF file](http://cl.ly/3E1K0X2q292G0c110w2h).
 10 | 
 11 | ## Requirements ##
 12 | 
 13 | - PHP 5.3 or higher
 14 | - OpenSSL
 15 | 
 16 | ## Usage ##
 17 | 
 18 | The usage of this class is really simple. It contains two public methods:
 19 | 
 20 | ```php
 21 | <?php
 22 |     require_once 'Bcrypt.php';
 23 |     
 24 |     // hash the password => returns hashed password
 25 |     Bcrypt::hashPassword($password);
 26 |     
 27 |     // check $password against the $hashedPassword => returns true/false
 28 |     Bcrypt::checkPassword($password, $hashedPassword);
 29 | ?>
 30 | ```
 31 | 
 32 | ## Options ##
 33 | 
 34 | ### Work factor ###
 35 | 
 36 | `Bcrypt::hashPassword($password, <$workFactor>)`
 37 | 
 38 | To increase your hash security this method accepts the optional parameter `$workFactor`. This defines the number of rounds.
 39 | With each round the creation time doubles, so the system is exponentially. If *one* round takes about `1 ms`, then *31* rounds would take ca. `74 minutes`.
 40 | 
 41 |     08 rounds = 2^8 iterations
 42 |     12 rounds = 2^12 iterations
 43 | 
 44 | ---
 45 | 
 46 | **Important:** `$workFactor` must be a *2 char* integer in the range between `04` and `31`. The default value is `12`.
 47 | 
 48 | ---
 49 | 
 50 | ```php
 51 | <?php
 52 |     $workFactor = 16;
 53 |     Bcrypt::hashPassword($password, $workFactor);
 54 | ?>
 55 | ```
 56 | 
 57 | Because the current work factor is [stored in the hash](#structure), it's not a fixed value. This allows you to adjust it, depending on your hardware capacity and upcoming traffic. As your hardware speed improves, the factor can be increased to compensate.
 58 | 
 59 | > Suitable values are in the range between `08` to `12`, depending on the hardware used and patience. [Good practice](http://stackoverflow.com/a/4766811).
 60 | 
 61 | ### Scheme ###
 62 | 
 63 | To alter the default scheme, change the variable `$_identifier` of the class to one of the following parameters (without $-signs):
 64 | 
 65 | - `$2a$` - Hash which is potentially generated with the buggy algorithm.
 66 | - `$2x$` - "compatibility" option the buggy Bcrypt implementation.
 67 | - `$2y$` - Hash generated with the new, corrected algorithm implementation *(crypt_blowfish 1.1 and newer)*.
 68 | 
 69 | ---
 70 | 
 71 | **Note:** The default scheme is `$2y$`, which makes use of the new, corrected hash implementation.  
 72 | *Other schemes should only be used, when comparing values produced by an old version.*
 73 | 
 74 | ---
 75 | 
 76 | ## Bcrypt ##
 77 | 
 78 | So what exactly is a Bcrypt? It is an adaptive hash function based on the Blowfish symmetric block cipher cryptographic algorithm. It uses a Work Factor which adjusts the cost of hashing. This ability, to increase the time and processing power of hashing, makes Bcrypt so powerful compared to other hashing methods.
 79 | 
 80 | - Its slowness and multiple rounds ensures high security (an attacker must deploy massive hardware to be able to crack the passwords).
 81 | - Bcrypt is an one-way hashing algorithm. This means that you cannot "decode" the plain password.
 82 | - Bcrypt PHP class hashes each password with a different salt.
 83 | 
 84 | ### Why should I use Bcrypt? ###
 85 | 
 86 | Some people believe MD5 would be a safe way to encode passwords - this is a lie! MD5 is a good method to obscure non-sensitive data, because it's quite fast.
 87 | However, this is a big disadvantage when it comes to password hashing. Using [rainbow tables](http://en.wikipedia.org/wiki/Rainbow_table) MD5 hashes can be very easily “decoded”.
 88 | 
 89 | That's the point where Bcrypt comes into play. Using a work factor of *12*, Bcrypt hashes the password in about *0.3 seconds*. MD5, on the other hand, takes less than *a microsecond*. If you still believe in MD5 as a secure password hasher, take a look at the following reference.
 90 | 
 91 | > You can test how easy it is to [crack MD5 encoded passwords](http://md5cracker.org/index-page-cracken.html).    
 92 | > Read more about [why you should use Bcrypt](http://phpmaster.com/why-you-should-use-bcrypt-to-hash-stored-passwords/).
 93 | 
 94 | ### Structure ###
 95 | 
 96 |     $2a$12$Some22CharacterSaltXXO6NC3ydPIrirIzk1NdnTz0L/aCaHnlBa
 97 | 
 98 | - `$2a$` tells PHP to use which [Blowfish scheme](#scheme) *(Bcrypt is based on Blowfish)*
 99 | - `12$`  is the number of [iterations](#work-factor) the hashing mechanism uses.
100 | - `Some22CharacterSaltXXO` is a random salt *(by OpenSSL)*
101 | 
102 | #### Diagram ####
103 | 
104 |     $2a$12$Some22CharacterSaltXXO6NC3ydPIrirIzk1NdnTz0L/aCaHnlBa
105 |     \___________________________/\_____________________________/
106 |       \                            \
107 |        \                            \ Actual Hash (31 chars)
108 |         \
109 |          \  $2a$   12$   Some22CharacterSaltXXO
110 |             \__/    \    \____________________/
111 |               \      \              \
112 |                \      \              \ Salt (22 chars)
113 |                 \      \
114 |                  \      \ Number of Rounds (work factor)
115 |                   \
116 |                    \ Hash Header
117 | 
118 | > Diagram based on [Andrew Moore's structure](http://stackoverflow.com/a/5343655).
119 | 
120 | ---
121 | 
122 | Please note, that there is ABSOLUTELY NO WARRANTY for this class.  
123 | The project is based on the great [phpass framework](http://www.openwall.com/phpass/).
124 | 
125 | ---
126 | 
127 | ## History ##
128 | 
129 | **Bcrypt PHP Class 1.0 - 23/06/2012**
130 | 
131 | - `release` First version
132 | - `update` Extensive documentation
133 | 
134 | ## Credits ##
135 | 
136 | Copyright (c) 2012 - Programmed by Christian Metz  
137 | Released under the [BSD License](http://www.opensource.org/licenses/bsd-license.php).


--------------------------------------------------------------------------------
/license.txt:
--------------------------------------------------------------------------------
 1 | Copyright (c) 2012, Christian Metz
 2 | All rights reserved.
 3 | 
 4 | Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 5 | 
 6 |     * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 7 |     * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 8 |     * Neither the name of the organisation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
 9 | 
10 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


--------------------------------------------------------------------------------