Subversion Repositories php_utils

Rev

Rev 67 | Rev 69 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed

  1. <?php
  2.  
  3. /*
  4.  * ViaThinkSoft Modular Crypt Format 1.0 / vts_password_hash() / vts_password_verify()
  5.  * Copyright 2023 Daniel Marschall, ViaThinkSoft
  6.  * Revision 2023-02-28
  7.  *
  8.  * Licensed under the Apache License, Version 2.0 (the "License");
  9.  * you may not use this file except in compliance with the License.
  10.  * You may obtain a copy of the License at
  11.  *
  12.  *     http://www.apache.org/licenses/LICENSE-2.0
  13.  *
  14.  * Unless required by applicable law or agreed to in writing, software
  15.  * distributed under the License is distributed on an "AS IS" BASIS,
  16.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17.  * See the License for the specific language governing permissions and
  18.  * limitations under the License.
  19.  */
  20.  
  21. /*
  22.  
  23. The function vts_password_hash() replaces password_hash()
  24. and adds the ViaThinkSoft Modular Crypt Format 1.0 hash as well as
  25. all hashes from password_hash() and crypt().
  26.  
  27. The function vts_password_verify() replaces password_verify().
  28.  
  29. ViaThinkSoft Modular Crypt Format 1.0 performs a simple hash or HMAC operation.
  30. No key derivation function or iterations are performed.
  31. Format:
  32.         $1.3.6.1.4.1.37476.3.0.1.1$a=<algo>,m=<mode>$<salt>$<hash>
  33. where <algo> is any valid hash algorithm (name scheme of PHP hash_algos() preferred), e.g.
  34.         sha3-512
  35.         sha3-384
  36.         sha3-256
  37.         sha3-224
  38.         sha512
  39.         sha512/256
  40.         sha512/224
  41.         sha384
  42.         sha256
  43.         sha224
  44.         sha1
  45.         md5
  46. Valid <mode> :
  47.         sp = salt + password
  48.         ps = password + salt
  49.         sps = salt + password + salt
  50.         hmac = HMAC (salt is the key)
  51.         pbkdf2 = PBKDF2-HMAC (Additional param i= contains the number of iterations)
  52. Like most Crypt-hashes, <salt> and <hash> are Radix64 coded
  53. with alphabet './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz' and no padding.
  54. Link to the online specification:
  55.         https://oidplus.viathinksoft.com/oidplus/?goto=oid%3A1.3.6.1.4.1.37476.3.0.1.1
  56. Reference implementation in PHP:
  57.         https://github.com/danielmarschall/php_utils/blob/master/vts_crypt.inc.php
  58.  
  59. */
  60.  
  61. require_once __DIR__ . '/misc_functions.inc.php';
  62.  
  63. define('OID_MCF_VTS_V1',     '1.3.6.1.4.1.37476.3.0.1.1'); // { iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) 37476 specifications(3) misc(0) modular-crypt-format(1) vts-crypt-v1(1) }
  64.  
  65. // Valid algorithms for vts_password_hash():
  66. define('PASSWORD_STD_DES',   'std_des');       // Algorithm from crypt()
  67. define('PASSWORD_EXT_DES',   'ext_des');       // Algorithm from crypt()
  68. define('PASSWORD_MD5',       'md5');           // Algorithm from crypt()
  69. define('PASSWORD_BLOWFISH',  'blowfish');      // Algorithm from crypt()
  70. define('PASSWORD_SHA256',    'sha256');        // Algorithm from crypt()
  71. define('PASSWORD_SHA512',    'sha512');        // Algorithm from crypt()
  72. define('PASSWORD_VTS_MCF1',  OID_MCF_VTS_V1);  // Algorithm from ViaThinkSoft
  73. // Other valid values (already defined in PHP):
  74. // - PASSWORD_DEFAULT
  75. // - PASSWORD_BCRYPT
  76. // - PASSWORD_ARGON2I
  77. // - PASSWORD_ARGON2ID
  78.  
  79. // --- Part 1: Modular Crypt Format encode/decode
  80.  
  81. function crypt_modular_format_encode($id, $bin_salt, $bin_hash, $params=null) {
  82.         // $<id>[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]]
  83.         $out = '$'.$id;
  84.         if (!is_null($params)) {
  85.                 $ary_params = array();
  86.                 foreach ($params as $name => $value) {
  87.                         $ary_params[] = "$name=$value";
  88.                 }
  89.                 $out .= '$'.implode(',',$ary_params);
  90.         }
  91.         $out .= '$'.crypt_radix64_encode($bin_salt);
  92.         $out .= '$'.crypt_radix64_encode($bin_hash);
  93.         return $out;
  94. }
  95.  
  96. function crypt_modular_format_decode($mcf) {
  97.         $ary = explode('$', $mcf);
  98.  
  99.         $dummy = array_shift($ary);
  100.         if ($dummy !== '') return false;
  101.  
  102.         $dummy = array_shift($ary);
  103.         $id = $dummy;
  104.  
  105.         $params = array();
  106.         $dummy = array_shift($ary);
  107.         if (strpos($dummy, '=') !== false) {
  108.                 $params_ary = explode(',',$dummy);
  109.                 foreach ($params_ary as $param) {
  110.                         $bry = explode('=', $param, 2);
  111.                         if (count($bry) > 1) {
  112.                                 $params[$bry[0]] = $bry[1];
  113.                         }
  114.                 }
  115.         } else {
  116.                 array_unshift($ary, $dummy);
  117.         }
  118.  
  119.         if (count($ary) > 1) {
  120.                 $dummy = array_shift($ary);
  121.                 $bin_salt = crypt_radix64_decode($dummy);
  122.         } else {
  123.                 $bin_salt = '';
  124.         }
  125.  
  126.         $dummy = array_shift($ary);
  127.         $bin_hash = crypt_radix64_decode($dummy);
  128.  
  129.         return array('id' => $id, 'salt' => $bin_salt, 'hash' => $bin_hash, 'params' => $params);
  130. }
  131.  
  132. // --- Part 2: ViaThinkSoft Modular Crypt Format 1.0
  133.  
  134. function vts_crypt_version($hash) {
  135.         if (str_starts_with($hash, '$'.OID_MCF_VTS_V1.'$')) {
  136.                 return '1';
  137.         } else {
  138.                 return '0';
  139.         }
  140. }
  141.  
  142. function vts_crypt_hash($algo, $str_password, $str_salt, $ver='1', $mode='ps', $iterations=0/*default*/) {
  143.         if ($ver == '1') {
  144.                 if ($mode == 'sp') {
  145.                         $payload = $str_salt.$str_password;
  146.                         if (!hash_supported_natively($algo) && str_starts_with($algo, 'sha3-') && method_exists('\bb\Sha3\Sha3', 'hash')) {
  147.                                 $bits = explode('-',$algo)[1];
  148.                                 $bin_hash = \bb\Sha3\Sha3::hash($payload, $bits, true);
  149.                         } else {
  150.                                 $bin_hash = hash($algo, $payload, true);
  151.                         }
  152.                 } else if ($mode == 'ps') {
  153.                         $payload = $str_password.$str_salt;
  154.                         if (!hash_supported_natively($algo) && str_starts_with($algo, 'sha3-') && method_exists('\bb\Sha3\Sha3', 'hash')) {
  155.                                 $bits = explode('-',$algo)[1];
  156.                                 $bin_hash = \bb\Sha3\Sha3::hash($payload, $bits, true);
  157.                         } else {
  158.                                 $bin_hash = hash($algo, $payload, true);
  159.                         }
  160.                 } else if ($mode == 'sps') {
  161.                         $payload = $str_salt.$str_password.$str_salt;
  162.                         if (!hash_supported_natively($algo) && str_starts_with($algo, 'sha3-') && method_exists('\bb\Sha3\Sha3', 'hash')) {
  163.                                 $bits = explode('-',$algo)[1];
  164.                                 $bin_hash = \bb\Sha3\Sha3::hash($payload, $bits, true);
  165.                         } else {
  166.                                 $bin_hash = hash($algo, $payload, true);
  167.                         }
  168.                 } else if ($mode == 'hmac') {
  169.                         if (!hash_hmac_supported_natively($algo) && str_starts_with($algo, 'sha3-') && method_exists('\bb\Sha3\Sha3', 'hash_hmac')) {
  170.                                 $bits = explode('-',$algo)[1];
  171.                                 $bin_hash = \bb\Sha3\Sha3::hash_hmac($str_password, $str_salt, $bits, true);
  172.                         } else {
  173.                                 $bin_hash = hash_hmac($algo, $str_password, $str_salt, true);
  174.                         }
  175.                 } else if ($mode == 'pbkdf2') {
  176.                         if (!hash_pbkdf2_supported_natively($algo) && str_starts_with($algo, 'sha3-') && method_exists('\bb\Sha3\Sha3', 'hash_pbkdf2')) {
  177.                                 if ($iterations == 0) {
  178.                                         $iterations = 2000; // because userland implementations are much slower, we must choose a small value...
  179.                                 }
  180.                                 $bits = explode('-',$algo)[1];
  181.                                 $bin_hash = \bb\Sha3\Sha3::hash_pbkdf2($str_password, $str_salt, $iterations, $bits, 0, true);
  182.                         } else {
  183.                                 if ($iterations == 0) {
  184.                                         // Recommendations taken from https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2
  185.                                         // Note that hash_pbkdf2() implements PBKDF2-HMAC-*
  186.                                         if      ($algo == 'sha3-512')    $iterations =  100000;
  187.                                         else if ($algo == 'sha3-384')    $iterations =  100000;
  188.                                         else if ($algo == 'sha3-256')    $iterations =  100000;
  189.                                         else if ($algo == 'sha3-224')    $iterations =  100000;
  190.                                         else if ($algo == 'sha512')      $iterations =  210000; // value by owasp.org cheatcheat (28 February 2023)
  191.                                         else if ($algo == 'sha512/256')  $iterations =  210000; // value by owasp.org cheatcheat (28 February 2023)
  192.                                         else if ($algo == 'sha512/224')  $iterations =  210000; // value by owasp.org cheatcheat (28 February 2023)
  193.                                         else if ($algo == 'sha384')      $iterations =  600000;
  194.                                         else if ($algo == 'sha256')      $iterations =  600000; // value by owasp.org cheatcheat (28 February 2023)
  195.                                         else if ($algo == 'sha224')      $iterations =  600000;
  196.                                         else if ($algo == 'sha1')        $iterations = 1300000; // value by owasp.org cheatcheat (28 February 2023)
  197.                                         else if ($algo == 'md5')         $iterations = 5000000;
  198.                                         else                             $iterations =    5000;
  199.                                 }
  200.                                 $bin_hash = hash_pbkdf2($algo, $str_password, $str_salt, $iterations, 0, true);
  201.                         }
  202.                 } else {
  203.                         throw new Exception("Invalid VTS crypt version 1 mode. Expect sp, ps, sps, hmac, or pbkdf2.");
  204.                 }
  205.                 $bin_salt = $str_salt;
  206.                 $params = array();
  207.                 $params['a'] = $algo;
  208.                 $params['m'] = $mode;
  209.                 if ($mode == 'pbkdf2') $params['i'] = $iterations;
  210.                 return crypt_modular_format_encode(OID_MCF_VTS_V1, $bin_salt, $bin_hash, $params);
  211.         } else {
  212.                 throw new Exception("Invalid VTS crypt version, expect 1.");
  213.         }
  214. }
  215.  
  216. function vts_crypt_verify($password, $hash): bool {
  217.         $ver = vts_crypt_version($hash);
  218.         if ($ver == '1') {
  219.                 // Decode the MCF hash parameters
  220.                 $data = crypt_modular_format_decode($hash);
  221.                 if ($data === false) throw new Exception('Invalid auth key');
  222.                 $id = $data['id'];
  223.                 $bin_salt = $data['salt'];
  224.                 $bin_hash = $data['hash'];
  225.                 $params = $data['params'];
  226.  
  227.                 if (!isset($params['a'])) throw new Exception('Param "a" (algo) missing');
  228.                 $algo = $params['a'];
  229.  
  230.                 if (!isset($params['m'])) throw new Exception('Param "m" (mode) missing');
  231.                 $mode = $params['m'];
  232.  
  233.                 if ($mode == 'pbkdf2') {
  234.                         if (!isset($params['i'])) throw new Exception('Param "i" (iterations) missing');
  235.                         $iterations = $params['i'];
  236.                 } else {
  237.                         $iterations = 0;
  238.                 }
  239.  
  240.                 // Create a VTS MCF 1.0 hash based on the parameters of $hash and the password $password
  241.                 $calc_authkey_1 = vts_crypt_hash($algo, $password, $bin_salt, $ver, $mode, $iterations);
  242.  
  243.                 // We rewrite the MCF to make sure that they match (if params have the wrong order)
  244.                 $calc_authkey_2 = crypt_modular_format_encode($id, $bin_salt, $bin_hash, $params);
  245.  
  246.                 return hash_equals($calc_authkey_1, $calc_authkey_2);
  247.         } else {
  248.                 throw new Exception("Invalid VTS crypt version, expect 1.");
  249.         }
  250. }
  251.  
  252. // --- Part 3: vts_password_hash() and vts_password_verify()
  253.  
  254. /** This function extends password_verify() by adding ViaThinkSoft Modular Crypt Format 1.0.
  255.  * @param string $password to be checked
  256.  * @param string $hash Hash created by crypt(), password_hash(), or vts_password_hash().
  257.  * @return bool true if password is valid
  258.  */
  259. function vts_password_verify($password, $hash): bool {
  260.         if (vts_crypt_version($hash) != '0') {
  261.                 // Hash created by vts_password_hash(), or vts_crypt_hash()
  262.                 return vts_crypt_verify($password, $hash);
  263.         } else {
  264.                 // Hash created by vts_password_hash(), password_hash(), or crypt()
  265.                 return password_verify($password, $hash);
  266.         }
  267. }
  268.  
  269. /** This function extends password_hash() with the algorithms supported by crypt().
  270.  * It also adds vts_crypt_hash() which implements the ViaThinkSoft Modular Crypt Format 1.0.
  271.  * The result can be verified using vts_password_verify().
  272.  * @param string $password to be hashed
  273.  * @param mixed $algo algorithm
  274.  * @param array $options options for the hashing algorithm
  275.  * @return string Crypt style password hash
  276.  */
  277. function vts_password_hash($password, $algo, $options=array()): string {
  278.         $crypt_salt = null;
  279.         if (($algo === PASSWORD_STD_DES) && defined('CRYPT_STD_DES')) {
  280.                 // Standard DES-based hash with a two character salt from the alphabet "./0-9A-Za-z". Using invalid characters in the salt will cause crypt() to fail.
  281.                 $crypt_salt = des_compat_salt(2);
  282.         } else if (($algo === PASSWORD_EXT_DES) && defined('CRYPT_EXT_DES')) {
  283.                 // Extended DES-based hash. The "salt" is a 9-character string consisting of an underscore followed by 4 characters of iteration count and 4 characters of salt. Each of these 4-character strings encode 24 bits, least significant character first. The values 0 to 63 are encoded as ./0-9A-Za-z. Using invalid characters in the salt will cause crypt() to fail.
  284.                 $iterations = isset($options['iterations']) ? $options['iterations'] : 725;
  285.                 $crypt_salt = '_' . base64_int_encode($iterations) . des_compat_salt(4);
  286.         } else if (($algo === PASSWORD_MD5) && defined('CRYPT_MD5')) {
  287.                 // MD5 hashing with a twelve character salt starting with $1$
  288.                 $crypt_salt = '$1$'.des_compat_salt(12).'$';
  289.         } else if (($algo === PASSWORD_BLOWFISH) && defined('CRYPT_BLOWFISH')) {
  290.                 // Blowfish hashing with a salt as follows: "$2a$", "$2x$" or "$2y$", a two digit cost parameter, "$", and 22 characters from the alphabet "./0-9A-Za-z". Using characters outside of this range in the salt will cause crypt() to return a zero-length string. The two digit cost parameter is the base-2 logarithm of the iteration count for the underlying Blowfish-based hashing algorithm and must be in range 04-31, values outside this range will cause crypt() to fail. "$2x$" hashes are potentially weak; "$2a$" hashes are compatible and mitigate this weakness. For new hashes, "$2y$" should be used.
  291.                 $algo = '$2y$'; // most secure
  292.                 $cost = isset($options['cost']) ? $options['cost'] : 10;
  293.                 $crypt_salt = $algo.str_pad($cost,2,'0',STR_PAD_LEFT).'$'.des_compat_salt(22).'$';
  294.         } else if (($algo === PASSWORD_SHA256) && defined('CRYPT_SHA256')) {
  295.                 // SHA-256 hash with a sixteen character salt prefixed with $5$. If the salt string starts with 'rounds=<N>$', the numeric value of N is used to indicate how many times the hashing loop should be executed, much like the cost parameter on Blowfish. The default number of rounds is 5000, there is a minimum of 1000 and a maximum of 999,999,999. Any selection of N outside this range will be truncated to the nearest limit.
  296.                 $algo = '$5$';
  297.                 $rounds = isset($options['rounds']) ? $options['rounds'] : 5000;
  298.                 $crypt_salt = $algo.'rounds='.$rounds.'$'.des_compat_salt(16).'$';
  299.         } else if (($algo === PASSWORD_SHA512) && defined('CRYPT_SHA512')) {
  300.                 // SHA-512 hash with a sixteen character salt prefixed with $6$. If the salt string starts with 'rounds=<N>$', the numeric value of N is used to indicate how many times the hashing loop should be executed, much like the cost parameter on Blowfish. The default number of rounds is 5000, there is a minimum of 1000 and a maximum of 999,999,999. Any selection of N outside this range will be truncated to the nearest limit.
  301.                 $algo = '$6$';
  302.                 $rounds = isset($options['rounds']) ? $options['rounds'] : 5000;
  303.                 $crypt_salt = $algo.'rounds='.$rounds.'$'.des_compat_salt(16).'$';
  304.         }
  305.  
  306.         if (!is_null($crypt_salt)) {
  307.                 // Algorithms: PASSWORD_STD_DES
  308.                 //             PASSWORD_EXT_DES
  309.                 //             PASSWORD_MD5
  310.                 //             PASSWORD_BLOWFISH
  311.                 //             PASSWORD_SHA256
  312.                 //             PASSWORD_SHA512
  313.                 $out = crypt($password, $crypt_salt);
  314.                 if (strlen($out) < 13) throw new Exception("crypt() failed");
  315.                 return $out;
  316.         } else if ($algo === PASSWORD_VTS_MCF1) {
  317.                 // Algorithms: PASSWORD_VTS_MCF1
  318.                 $ver  = '1';
  319.                 $algo = isset($options['algo']) ? $options['algo'] : 'sha3-512';
  320.                 $mode = isset($options['mode']) ? $options['mode'] : 'ps';
  321.                 $iterations = isset($options['iterations']) ? $options['iterations'] : 0/*default*/;
  322.                 $salt_len = isset($options['salt_length']) ? $options['salt_length'] : 50;
  323.                 $salt = random_bytes_ex($salt_len, true, true);
  324.                 return vts_crypt_hash($algo, $password, $salt, $ver, $mode, $iterations);
  325.         } else {
  326.                 // Algorithms: PASSWORD_DEFAULT
  327.                 //             PASSWORD_BCRYPT
  328.                 //             PASSWORD_ARGON2I
  329.                 //             PASSWORD_ARGON2ID
  330.                 return password_hash($password, $algo, $options);
  331.         }
  332. }
  333.  
  334. // --- Part 4: Useful functions required by the crypt-functions
  335.  
  336. define('BASE64_RFC4648_ALPHABET', '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz+/');
  337. define('BASE64_CRYPT_ALPHABET',   './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz');
  338.  
  339. function des_compat_salt($salt_len) {
  340.         if ($salt_len <= 0) return '';
  341.         $characters = BASE64_CRYPT_ALPHABET;
  342.         $salt = '';
  343.         $bytes = random_bytes_ex($salt_len, true, true);
  344.         for ($i=0; $i<$salt_len; $i++) {
  345.                 $salt .= $characters[ord($bytes[$i]) % strlen($characters)];
  346.         }
  347.         return $salt;
  348. }
  349.  
  350. function base64_int_encode($num) {
  351.         // https://stackoverflow.com/questions/15534982/which-iteration-rules-apply-on-crypt-using-crypt-ext-des
  352.         $alphabet_raw = BASE64_CRYPT_ALPHABET;
  353.         $alphabet = str_split($alphabet_raw);
  354.         $arr = array();
  355.         $base = sizeof($alphabet);
  356.         while ($num) {
  357.                 $rem = $num % $base;
  358.                 $num = (int)($num / $base);
  359.                 $arr[] = $alphabet[$rem];
  360.         }
  361.         $string = implode($arr);
  362.         return str_pad($string, 4, '.', STR_PAD_RIGHT);
  363. }
  364.  
  365. function crypt_radix64_encode($str) {
  366.         $x = $str;
  367.         $x = base64_encode($x);
  368.         $x = rtrim($x, '='); // remove padding
  369.         $x = strtr($x, BASE64_RFC4648_ALPHABET, BASE64_CRYPT_ALPHABET);
  370.         return $x;
  371. }
  372.  
  373. function crypt_radix64_decode($str) {
  374.         $x = $str;
  375.         $x = strtr($x, BASE64_CRYPT_ALPHABET, BASE64_RFC4648_ALPHABET);
  376.         $x = base64_decode($x);
  377.         return $x;
  378. }
  379.  
  380. function hash_supported_natively($algo) {
  381.         if (version_compare(PHP_VERSION, '5.1.2') >= 0) {
  382.                 return in_array($algo, hash_algos());
  383.         } else {
  384.                 return false;
  385.         }
  386. }
  387.  
  388. function hash_hmac_supported_natively($algo): bool {
  389.         if (version_compare(PHP_VERSION, '7.2.0') >= 0) {
  390.                 return in_array($algo, hash_hmac_algos());
  391.         } else if (version_compare(PHP_VERSION, '5.1.2') >= 0) {
  392.                 return in_array($algo, hash_algos());
  393.         } else {
  394.                 return false;
  395.         }
  396. }
  397.  
  398. function hash_pbkdf2_supported_natively($algo) {
  399.         return hash_supported_natively($algo);
  400. }
  401.  
  402. // --- Part 5: Selftest
  403.  
  404. /*
  405. $rnd = random_bytes_ex(50, true, true);
  406. assert(crypt_radix64_decode(crypt_radix64_encode($rnd)) === $rnd);
  407.  
  408. $password = random_bytes_ex(20, false, true);
  409. assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_STD_DES)));
  410. assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_EXT_DES)));
  411. assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_MD5)));
  412. assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_BLOWFISH)));
  413. assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_SHA256)));
  414. assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_SHA512)));
  415. assert(vts_password_verify($password,$debug = vts_password_hash($password, PASSWORD_VTS_MCF1, array(
  416.         'algo' => 'sha3-512',
  417.         'mode' => 'pbkdf2',
  418.         'iterations' => 5000
  419. ))));
  420. echo "$debug\n";
  421. assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_DEFAULT)));
  422. assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_BCRYPT)));
  423. if (defined('PASSWORD_ARGON2I'))
  424.         assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_ARGON2I)));
  425. if (defined('PASSWORD_ARGON2ID'))
  426.         assert(vts_password_verify($password,vts_password_hash($password, PASSWORD_ARGON2ID)));
  427. echo "OK, Password $password\n";
  428. */
  429.