Developers/Security/Configure password hash

From Aimeos documentation

Developers
Other languages:
English 100%


2016.x version

Aimeos is a component based shop that integrates into your application and it have to use the same password hashing method for customer accounts so authentication can succeed. There are a few standard methods like the password_hash() function impemented in PHP 5.5 and later but even the output of well known functions like for SHA1 might be not equal due to different ways of salting passwords. For example, the hashes are totally different for these two combination methods:

sha1( 'password-salt' )
sha1( '{salt}password' )

Since core version 2015.01, Aimeos provides an easy and flexible way to adapt the password hashing of the core to the method used by your application. It provides a few configurable standard algorithms and an interface for implementing your own hashing method. The encode() method of the interface is reponsible to create a hash from the given password and salt:

$hash = $helper->encode( $password, $salt );

Configuration

Changing the used implementation for the customer hashing can be done via the mshop/customer/manager/password/name configuration option in the mshop.php config file:

  1. <?php
  2. return array(
  3.   'customer' => array(
  4.     'manager' => array(
  5.       'password' => array(
  6.         'name' => 'Bcrypt'
  7.       )
  8.     )
  9.   )
  10. );

Besides the PHP configuration files, applications may provide different ways or formats for configuration, mayby YAML, XML or some scripting language. Please have a look into application specific sections of the documentation to find out what kind of configuration possibilities are supported.

Each password hashing implementation can use an arbitrary number of options to specify the method in more detail. All options must be provided below the mshop/customer/manager/password/options key like:

  1. <?php
  2. return array(
  3.   'customer' => array(
  4.     'manager' => array(
  5.       'password' => array(
  6.         'name' => 'Hash',
  7.         'options' => array(
  8.           'algorithm' => 'sha512',
  9.           'format' => '{%2$s}%1$s',
  10.         )
  11.       )
  12.     )
  13.   )
  14. );

The customer managers additionally support an instance wide salt if no specific salt is available for each customer entry in the database. The salt used by all passwords can be configured using the mshop/customer/manager/salt option:

  1. <?php
  2. return array(
  3.   'customer' => array(
  4.     'manager' => array(
  5.       'salt' => 'qh4tp9h4',
  6.     )
  7.   )
  8. );

Using an application wide salt for all passwords is better than using no salt but you should always try to use a specific salt for each password. Otherwise, attackers are able to crack stolen passwords in a much shorter time.

Default

The default password hashing method is based on SHA1 using a configurable format for the salted password.

format (string, default is "%1$s%2$s") 
Format string used by sprintf() to create a password/salt combination in any order and with all required separator characters. The default order is password first (%1$s) and salt at the end (%2$s). To reverse the order, you can reverse the numbers used in the format string like "%2$s%1$s". Additional separators are inserted literally like "{%2$s}%1$s". In case of a percent sign as separator, it must be quoted with another percent sign (%%).

Hash

This implementation provides all hash algorithms supported by the PHP Hash extension and its hash() function. The "algorithm" configuration option is mandatory in this case.

algorithm (string, mandatory) 
Name of the hash algorithm used and which is supported by the PHP Hash extension. Please have a look into the PHP documentation for the names of the supported algorithms.
format (string, default is "%1$s%2$s") 
Format string used by sprintf() to create a password/salt combination in any order and with all required separator characters. The default order is password first (%1$s) and salt at the end (%2$s). To reverse the order, you can reverse the numbers used in the format string like "%2$s%1$s". Additional separators are inserted literally like "{%2$s}%1$s". In case of a percent sign as separator, it must be quoted with another percent sign (%%).
iterations (positive integer, default is 1) 
The number of times the hash algorithm is applied to the password/salt combination. For the second and all following iterations, the computed hash is the first part and the password/hash the second part of the input for the hash function. The hash should be more secure the more number of interations are used.
base64 (boolean, default is false) 
The computed hash can be encoded into the base64 format before it is returned. By default, a hexadecimal representation of the hash is given back.

Bcrypt

Since version 5.5, PHP provides an easy to use and secure password hashing function that uses a pre-defined format and generates salts by its own. This should be the preferred way in new applications.

If you hand over a salt as second parameter to the encode() method, this one is used instead of generating one. The salt must be at lease 22 characters long. To use a generated salt for each password, please provide NULL as second parameter which should be preferred.

cost (integer, default is 10) 
The algorithmic cost for creating the password hash. The higher the cost, the longer it will take to crack the password but also to compute the hash for verification.

Own implementations

To create a new way of hashing passwords, you only have to create a class that must implement the "Aimeos\MShop\Common\Item\Helper\Password\Iface":

  1. namespace Aimeos\MShop\Common\Item\Helper\Password;
  2.  
  3. interface Iface
  4. {
  5.     /**
  6.      * Initializes the password helper.
  7.      * 
  8.      * @param array Associative list of key/value pairs of options specific for the hashing method
  9.      */
  10.     public function __construct( array $options );
  11.  
  12.     /**
  13.      * Returns the hashed password.
  14.      *
  15.      * @return string Hashed password
  16.      */
  17.     public function encode( $password, $salt );
  18. }

A simple implementation placed in the lib/custom/src/MShop/Common/Item/Helper/Password/ directory of your application or project specific extension could be:

  1. namespace Aimeos\MShop\Common\Item\Helper\Password;
  2.  
  3. class Myhelper
  4.     implements Aimeos\MShop\Common\Item\Helper\Password\Iface
  5. {
  6.     private $_options = array();
  7.  
  8.     public function __construct( array $options )
  9.     {
  10. 	$this->_options = $options;
  11.     }
  12.  
  13.     /**
  14.      * Returns the hashed password.
  15.      *
  16.      * @return string Hashed password
  17.      */
  18.     public function encode( $password, $salt )
  19.     {
  20. 	return sha1( $password . $salt );
  21.     }
  22. }

Use the Aimeos extension builder to create an extension for your shop site. The generated extension skeletons contains all necessary directories and configuration to be used out of the box.