[Summary view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * V4 UUID generator.
  19   *
  20   * @package    core
  21   * @copyright  2019 Matteo Scaramuccia <moodle@matteoscaramuccia.com>
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace core;
  26  
  27  use Exception;
  28  
  29  defined('MOODLE_INTERNAL') || die();
  30  
  31  /**
  32   * V4 UUID generator class.
  33   *
  34   * @package    core
  35   * @copyright  2019 Matteo Scaramuccia <moodle@matteoscaramuccia.com>
  36   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  37   */
  38  class uuid {
  39      /**
  40       * Generate a V4 UUID using PECL UUID extension.
  41       * @see https://github.com/php/pecl-networking-uuid PECL uuid
  42       * @see https://tools.ietf.org/html/rfc4122
  43       *
  44       * @return string|bool The UUID when PECL UUID extension is available;
  45       *                     otherwise, false.
  46       */
  47      protected static function generate_uuid_via_pecl_uuid_extension() {
  48          $uuid = false;
  49  
  50          // Check if PECL uuid extension has been actually installed.
  51          if (function_exists('\uuid_time')) {
  52              // Set V4 version.
  53              $uuid = \uuid_create(UUID_TYPE_RANDOM);
  54          }
  55  
  56          return $uuid;
  57      }
  58  
  59      /**
  60       * Generate a V4 UUID using PHP 7+ features.
  61       *
  62       * @see https://www.php.net/manual/en/function.random-bytes.php
  63       * @see https://tools.ietf.org/html/rfc4122
  64       *
  65       * @return string|bool The UUID when random_bytes() function is available;
  66       *                     otherwise, false when missing the sources of randomness used by random_bytes().
  67       */
  68      protected static function generate_uuid_via_random_bytes() {
  69          $uuid = false;
  70  
  71          // If none of the sources of randomness are available,
  72          // then an Exception will be thrown.
  73          try {
  74              $data = random_bytes(16);
  75              $data[6] = chr((ord($data[6]) & 0x0f) | 0x40); // Set version to 0100.
  76              $data[8] = chr((ord($data[8]) & 0x3f) | 0x80); // Set bits 6-7 to 10.
  77              $uuid = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
  78          } catch (Exception $e) {
  79              // Could not generate a random string. Is this OS secure?
  80              $uuid = false;
  81          }
  82  
  83          return $uuid;
  84      }
  85  
  86      /**
  87       * Generate a V4 UUID.
  88       *
  89       * Unique is hard. Very hard. Attempt to use the PECL UUID function if available, and if not then revert to
  90       * constructing the uuid using random_bytes or mt_rand.
  91       *
  92       * It is important that this token is not solely based on time as this could lead
  93       * to duplicates in a clustered environment (especially on VMs due to poor time precision).
  94       *
  95       * UUIDs are just 128 bits long but with different supported versions (RFC 4122), mainly two:
  96       * - V1: the goal is uniqueness, at the cost of anonymity since it is coupled to the host generating it, via its MAC address.
  97       * - V4: the goal is randomness, at the cost of (rare) collisions.
  98       * Here, the V4 type is the preferred choice.
  99       *
 100       * The format is:
 101       * xxxxxxxx-xxxx-4xxx-Yxxx-xxxxxxxxxxxx
 102       * where x is any hexadecimal digit and Y is a random choice from 8, 9, a, or b.
 103       *
 104       * @see https://tools.ietf.org/html/rfc4122
 105       *
 106       * @return string The V4 UUID.
 107       */
 108      public static function generate() {
 109          // Try PHP UUID extensions first.
 110          $uuid = self::generate_uuid_via_pecl_uuid_extension();
 111  
 112          // Fall back to better random features, when possible.
 113          if (empty($uuid)) {
 114              $uuid = self::generate_uuid_via_random_bytes();
 115          }
 116  
 117          // Finally, create it with the available randomness.
 118          if (empty($uuid)) {
 119              // Fallback uuid generation based on:
 120              // "http://www.php.net/manual/en/function.uniqid.php#94959".
 121              $uuid = sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
 122  
 123                  // 32 bits for "time_low".
 124                  mt_rand(0, 0xffff), mt_rand(0, 0xffff),
 125  
 126                  // 16 bits for "time_mid".
 127                  mt_rand(0, 0xffff),
 128  
 129                  // 16 bits for "time_hi_and_version",
 130                  // four most significant bits holds version number 4.
 131                  mt_rand(0, 0x0fff) | 0x4000,
 132  
 133                  // 16 bits, 8 bits for "clk_seq_hi_res",
 134                  // 8 bits for "clk_seq_low",
 135                  // two most significant bits holds zero and one for variant DCE1.1.
 136                  mt_rand(0, 0x3fff) | 0x8000,
 137  
 138                  // 48 bits for "node".
 139                  mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff));
 140          }
 141  
 142          return trim($uuid);
 143      }
 144  }