1<?php 2 3namespace Drupal\Component\Utility; 4 5/** 6 * Utility class for cryptographically-secure string handling routines. 7 * 8 * @ingroup utility 9 */ 10class Crypt { 11 12 /** 13 * Returns a string of highly randomized bytes (over the full 8-bit range). 14 * 15 * This function is better than simply calling mt_rand() or any other built-in 16 * PHP function because it can return a long string of bytes (compared to < 4 17 * bytes normally from mt_rand()) and uses the best available pseudo-random 18 * source. 19 * 20 * In PHP 7 and up, this uses the built-in PHP function random_bytes(). 21 * In older PHP versions, this uses the random_bytes() function provided by 22 * the random_compat library, or the fallback hash-based generator from Drupal 23 * 7.x. 24 * 25 * @param int $count 26 * The number of characters (bytes) to return in the string. 27 * 28 * @return string 29 * A randomly generated string. 30 * 31 * @deprecated in drupal:8.8.0 and is removed from drupal:9.0.0. 32 * Use PHP's built-in random_bytes() function instead. 33 * 34 * @see https://www.drupal.org/node/3057191 35 */ 36 public static function randomBytes($count) { 37 @trigger_error(__CLASS__ . '::randomBytes() is deprecated in Drupal 8.8.0 and will be removed before Drupal 9.0.0. Use PHP\'s built-in random_bytes() function instead. See https://www.drupal.org/node/3057191', E_USER_DEPRECATED); 38 return random_bytes($count); 39 } 40 41 /** 42 * Calculates a base-64 encoded, URL-safe sha-256 hmac. 43 * 44 * @param mixed $data 45 * Scalar value to be validated with the hmac. 46 * @param mixed $key 47 * A secret key, this can be any scalar value. 48 * 49 * @return string 50 * A base-64 encoded sha-256 hmac, with + replaced with -, / with _ and 51 * any = padding characters removed. 52 */ 53 public static function hmacBase64($data, $key) { 54 // $data and $key being strings here is necessary to avoid empty string 55 // results of the hash function if they are not scalar values. As this 56 // function is used in security-critical contexts like token validation it 57 // is important that it never returns an empty string. 58 if (!is_scalar($data) || !is_scalar($key)) { 59 throw new \InvalidArgumentException('Both parameters passed to \Drupal\Component\Utility\Crypt::hmacBase64 must be scalar values.'); 60 } 61 62 $hmac = base64_encode(hash_hmac('sha256', $data, $key, TRUE)); 63 // Modify the hmac so it's safe to use in URLs. 64 return str_replace(['+', '/', '='], ['-', '_', ''], $hmac); 65 } 66 67 /** 68 * Calculates a base-64 encoded, URL-safe sha-256 hash. 69 * 70 * @param string $data 71 * String to be hashed. 72 * 73 * @return string 74 * A base-64 encoded sha-256 hash, with + replaced with -, / with _ and 75 * any = padding characters removed. 76 */ 77 public static function hashBase64($data) { 78 $hash = base64_encode(hash('sha256', $data, TRUE)); 79 // Modify the hash so it's safe to use in URLs. 80 return str_replace(['+', '/', '='], ['-', '_', ''], $hash); 81 } 82 83 /** 84 * Compares strings in constant time. 85 * 86 * @param string $known_string 87 * The expected string. 88 * @param string $user_string 89 * The user supplied string to check. 90 * 91 * @return bool 92 * Returns TRUE when the two strings are equal, FALSE otherwise. 93 * 94 * @deprecated in drupal:8.8.0 and is removed from drupal:9.0.0. 95 * Use PHP's built-in hash_equals() function instead. 96 * 97 * @see https://www.drupal.org/node/3054488 98 */ 99 public static function hashEquals($known_string, $user_string) { 100 @trigger_error(__CLASS__ . '::hashEquals() is deprecated in drupal:8.8.0 and is removed from drupal:9.0.0. Use PHP\'s built-in hash_equals() function instead. See https://www.drupal.org/node/3054488', E_USER_DEPRECATED); 101 return hash_equals($known_string, $user_string); 102 } 103 104 /** 105 * Returns a URL-safe, base64 encoded string of highly randomized bytes. 106 * 107 * @param $count 108 * The number of random bytes to fetch and base64 encode. 109 * 110 * @return string 111 * A base-64 encoded string, with + replaced with -, / with _ and any = 112 * padding characters removed. 113 * 114 * @see \Drupal\Component\Utility\Crypt::randomBytes() 115 */ 116 public static function randomBytesBase64($count = 32) { 117 return str_replace(['+', '/', '='], ['-', '_', ''], base64_encode(random_bytes($count))); 118 } 119 120} 121