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