Crypt.php 4.21 KB
Newer Older
1 2 3 4 5 6
<?php

namespace Drupal\Component\Utility;

/**
 * Utility class for cryptographically-secure string handling routines.
7 8
 *
 * @ingroup utility
9 10 11 12 13 14 15 16 17 18 19
 */
class Crypt {

  /**
   * Returns a string of highly randomized bytes (over the full 8-bit range).
   *
   * This function is better than simply calling mt_rand() or any other built-in
   * PHP function because it can return a long string of bytes (compared to < 4
   * bytes normally from mt_rand()) and uses the best available pseudo-random
   * source.
   *
20 21
   * In PHP 7 and up, this uses the built-in PHP function random_bytes().
   * In older PHP versions, this uses the random_bytes() function provided by
22 23
   * the random_compat library, or the fallback hash-based generator from Drupal
   * 7.x.
24
   *
25 26 27 28 29
   * @param int $count
   *   The number of characters (bytes) to return in the string.
   *
   * @return string
   *   A randomly generated string.
30
   *
31 32 33 34
   * @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/3054488
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/3054488', E_USER_DEPRECATED);
38
    return random_bytes($count);
39 40 41 42 43
  }

  /**
   * Calculates a base-64 encoded, URL-safe sha-256 hmac.
   *
44 45 46 47
   * @param mixed $data
   *   Scalar value to be validated with the hmac.
   * @param mixed $key
   *   A secret key, this can be any scalar value.
48 49 50 51 52 53
   *
   * @return string
   *   A base-64 encoded sha-256 hmac, with + replaced with -, / with _ and
   *   any = padding characters removed.
   */
  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 57 58 59 60 61 62
    // function is used in security-critical contexts like token validation it
    // is important that it never returns an empty string.
    if (!is_scalar($data) || !is_scalar($key)) {
      throw new \InvalidArgumentException('Both parameters passed to \Drupal\Component\Utility\Crypt::hmacBase64 must be scalar values.');
    }

    $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 69 70 71 72 73 74 75 76 77 78 79
  }

  /**
   * Calculates a base-64 encoded, URL-safe sha-256 hash.
   *
   * @param string $data
   *   String to be hashed.
   *
   * @return string
   *   A base-64 encoded sha-256 hash, with + replaced with -, / with _ and
   *   any = padding characters removed.
   */
  public static function hashBase64($data) {
    $hash = base64_encode(hash('sha256', $data, TRUE));
    // Modify the hash so it's safe to use in URLs.
80
    return str_replace(['+', '/', '='], ['-', '_', ''], $hash);
81 82
  }

83 84 85 86 87 88 89 90 91 92
  /**
   * Compares strings in constant time.
   *
   * @param string $known_string
   *   The expected string.
   * @param string $user_string
   *   The user supplied string to check.
   *
   * @return bool
   *   Returns TRUE when the two strings are equal, FALSE otherwise.
93
   *
94 95 96 97
   * @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
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
   *   The base64 encoded result will have a length of up to 4 * $count.
112 113 114
   *
   * @see \Drupal\Component\Utility\Crypt::randomBytes()
   */
115
  public static function randomBytesBase64($count = 32) {
116
    return str_replace(['+', '/', '='], ['-', '_', ''], base64_encode(random_bytes($count)));
117 118 119
  }

}