Subversion Repositories uuid_mac_utils

<?php

/*

 * UUID utils for PHP

 * Copyright 2011 - 2023 Daniel Marschall, ViaThinkSoft

 * Version 2023-07-11

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *     http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

# This library requires either the GMP extension (or BCMath if gmp_supplement.inc.php is present)

if (file_exists(__DIR__ . '/mac_utils.inc.phps')) include_once __DIR__ . '/mac_utils.inc.phps'; // optionally used for uuid_info()

if (file_exists(__DIR__ . '/gmp_supplement.inc.php')) include_once __DIR__ . '/gmp_supplement.inc.php';

define('UUID_NAMEBASED_NS_DNS',     '6ba7b810-9dad-11d1-80b4-00c04fd430c8'); // FQDN

define('UUID_NAMEBASED_NS_URL',     '6ba7b811-9dad-11d1-80b4-00c04fd430c8');

define('UUID_NAMEBASED_NS_OID',     '6ba7b812-9dad-11d1-80b4-00c04fd430c8');

define('UUID_NAMEBASED_NS_X500_DN', '6ba7b814-9dad-11d1-80b4-00c04fd430c8'); // DER according to https://github.com/cjsv/uuid/blob/master/Doc ?!

function _random_int($min, $max) {

        // This function tries a CSRNG and falls back to a RNG if no CSRNG is available

        try {

                return random_int($min, $max);

        } catch (Exception $e) {

                return mt_rand($min, $max);

        }

}

function uuid_valid($uuid) {

        $uuid = str_replace(array('-', '{', '}'), '', $uuid);

        $uuid = strtoupper($uuid);

        #$uuid = trim($uuid);

        if (strlen($uuid) != 32) return false;

        $uuid = preg_replace('@[0-9A-F]@i', '', $uuid);

        return ($uuid == '');

}

function uuid_info($uuid, $echo=true) {

        if (!uuid_valid($uuid)) return false;

        if (!$echo) ob_start();

        #$uuid = trim($uuid);

        # $uuid = str_replace(array('-', '{', '}'), '', $uuid);

        $uuid = strtolower($uuid);

        $uuid = preg_replace('@[^0-9A-F]@i', '', $uuid);

        $x = hexdec(substr($uuid, 16, 1));

             if ($x >= 14 /* 0b1110 */) $variant = 3;

        else if ($x >= 12 /* 0b110_ */) $variant = 2;

        else if ($x >=  8 /* 0b10__ */) $variant = 1;

        else if ($x >=  0 /* 0b0___ */) $variant = 0;

        else $variant = -1; // should not happen

        switch ($variant) {

                case 0:

                        echo sprintf("%-32s %s\n", "Variant:", "[0b0__] NCS (reserved for backward compatibility)");

                        /*

                         * Internal structure of variant #0 UUIDs

                         *

                         * The first 6 octets are the number of 4 usec units of time that have

                         * passed since 1/1/80 0000 GMT.  The next 2 octets are reserved for

                         * future use.  The next octet is an address family.  The next 7 octets

                         * are a host ID in the form allowed by the specified address family.

                         *

                         * Note that while the family field (octet 8) was originally conceived

                         * of as being able to hold values in the range [0..255], only [0..13]

                         * were ever used.  Thus, the 2 MSB of this field are always 0 and are

                         * used to distinguish old and current UUID forms.

                         */

                        /*

                        Variant 0 UUID

                        - 32 bit High Time

                        - 16 bit Low Time

                        - 16 bit Reserved

                        -  1 bit Variant (fix 0b0)

                        -  7 bit Family

                        - 56 bit Node

                        */

                        // Example of an UUID: 333a2276-0000-0000-0d00-00809c000000

                        # see also some notes at See https://github.com/cjsv/uuid/blob/master/Doc

                        /*

                        NOTE: A generator is not possible, because there are no timestamps left!

                        The last possible timestamp was:

                            [0xFFFFFFFFFFFF] 2015-09-05 05:58:26'210655 GMT

                        That is in the following UUID:

                            ffffffff-ffff-0000-027f-000001000000

                        Current timestamp generator:

                            echo dechex(round((microtime(true)+315532800)*250000));

                        */

                        # Timestamp: Count of 4us intervals since 01 Jan 1980 00:00:00 GMT

                        # 1/0,000004 = 250000

                        # Seconds between 1970 and 1980 : 315532800

                        # 250000*315532800=78883200000000

                        $timestamp = substr($uuid, 0, 12);

                        $ts = gmp_init($timestamp, 16);

                        $ts = gmp_add($ts, gmp_init("78883200000000", 10));

                        $ms = gmp_mod($ts, gmp_init("250000", 10));

                        $ts = gmp_div($ts, gmp_init("250000", 10));

                        $ts = gmp_strval($ts, 10);

                        $ms = gmp_strval($ms, 10);

                        $ts = gmdate('Y-m-d H:i:s', intval($ts))."'".str_pad($ms, 6/*us*/, '0', STR_PAD_LEFT).' GMT';

                        echo sprintf("%-32s %s\n", "Timestamp:", "[0x$timestamp] $ts");

                        $reserved = substr($uuid, 12, 4);

                        echo sprintf("%-32s %s\n", "Reserved:", "[0x$reserved]");

                        $family_hex = substr($uuid, 16, 2);

                        $family_dec = hexdec($family_hex);

                        $nodeid_hex = substr($uuid, 18, 14);

                        $nodeid_dec = hexdec($nodeid_hex);

                        if ($family_dec == 2) {

                                $family_name = 'IP';

                                // https://www.ibm.com/docs/en/aix/7.1?topic=u-uuid-gen-command-ncs (AIX 7.1) shows the following example output for /etc/ncs/uuid_gen -P

                                // := [

                                //    time_high := 16#458487df,

                                //    time_low := 16#9fb2,

                                //    reserved := 16#000,

                                //    family := chr(16#02),

                                //    host := [chr(16#c0), chr(16#64), chr(16#02), chr(16#03),

                                //             chr(16#00), chr(16#00), chr(16#00)]

                                //    ]

                                // This means that the IP address is 32 bits hex, and 32 bits are unused

                                $nodeid_desc = hexdec(substr($nodeid_hex,0,2)).'.'.

                                               hexdec(substr($nodeid_hex,2,2)).'.'.

                                               hexdec(substr($nodeid_hex,4,2)).'.'.

                                               hexdec(substr($nodeid_hex,6,2));

                                $rest = substr($nodeid_hex,8,6);

                                if ($rest != '000000') $nodeid_desc .= " + unexpected rest 0x$rest";

                        } else if ($family_dec == 13) {

                                $family_name = 'DDS (Data Link)';

                                // https://www.ibm.com/docs/en/aix/7.1?topic=u-uuid-gen-command-ncs (AIX 7.1) shows the following example output for /etc/ncs/uuid_gen -C

                                // = { 0x34dc23af,

                                //    0xf000,

                                //    0x0000,

                                //    0x0d,

                                //    {0x00, 0x00, 0x7c, 0x5f, 0x00, 0x00, 0x00} };

                                // https://github.com/cjsv/uuid/blob/master/Doc writes:

                                //    "Family 13 (dds) looks like node is 00 | nnnnnn 000000."

                                $nodeid_desc = '';

                                $start = substr($nodeid_hex,0,2);

                                if ($start != '00') $nodeid_desc .= "unexpected start 0x$start + ";

                                $nodeid_desc .= ($nodeid_dec >> 24) & 0xFFFFFF;

                                $rest = substr($nodeid_hex,8,6);

                                if ($rest != '000000') $nodeid_desc .= " + unexpected rest 0x$rest";

                        } else {

                                $family_name = "Unknown (Family $family_dec)"; # There are probably no more families

                                $nodeid_desc = "Unknown";

                        }

                        echo sprintf("%-32s %s\n", "Family:", "[0x$family_hex] $family_name");

                        echo sprintf("%-32s %s\n", "Node ID:", "[0x$nodeid_hex] $nodeid_desc");

                        break;

                case 1:

                        $version = hexdec(substr($uuid, 12, 1));

                        if ($version <= 2) {

                                echo sprintf("%-32s %s\n", "Variant:", "[0b10_] RFC 4122 (Leach-Mealling-Salz) / DCE 1.1");

                        } else if (($version >= 3) && ($version <= 5)) {

                                echo sprintf("%-32s %s\n", "Variant:", "[0b10_] RFC 4122 (Leach-Mealling-Salz)");

                        } else if (($version >= 6) && ($version <= 8)) {

                                echo sprintf("%-32s %s\n", "Variant:", "[0b10_] RFC 4122bis (Leach-Mealling-Peabody-Davis)");

                        } else {

                                echo sprintf("%-32s %s\n", "Variant:", "[0b10_] RFC 4122 ?");

                        }

                        switch ($version) {

                                case 6:

                                        /*

                                        Variant 1, Version 6 UUID

                                        - 48 bit High Time

                                        -  4 bit Version (fix 0x6)

                                        - 12 bit Low Time

                                        -  2 bit Variant (fix 0b10)

                                        -  6 bit Clock Seq High

                                        -  8 bit Clock Seq Low

                                        - 48 bit MAC Address

                                        */

                                        echo sprintf("%-32s %s\n", "Version:", "[$version] Reordered Time");

                                        $uuid = substr($uuid,  0, 8).'-'.

                                                substr($uuid,  8, 4).'-'.

                                                substr($uuid, 12, 4).'-'.

                                                substr($uuid, 16, 4).'-'.

                                                substr($uuid, 20, 12);

                                        $uuid = uuid6_to_uuid1($uuid);

                                        $uuid = str_replace('-', '', $uuid);

                                /* fallthrough */

                                case 1:

                                        /*

                                        Variant 1, Version 1 UUID

                                        - 32 bit Low Time

                                        - 16 bit Mid Time

                                        -  4 bit Version (fix 0x1)

                                        - 12 bit High Time

                                        -  2 bit Variant (fix 0b10)

                                        -  6 bit Clock Seq High

                                        -  8 bit Clock Seq Low

                                        - 48 bit MAC Address

                                        */

                                        if ($version == 1) echo sprintf("%-32s %s\n", "Version:", "[1] Time-based with unique random host identifier");

                                        # Timestamp: Count of 100ns intervals since 15 Oct 1582 00:00:00

                                        # 1/0,0000001 = 10000000

                                        $timestamp = substr($uuid, 13, 3).substr($uuid, 8, 4).substr($uuid, 0, 8);

                                        $ts = gmp_init($timestamp, 16);

                                        $ts = gmp_sub($ts, gmp_init("122192928000000000", 10));

                                        $ms = gmp_mod($ts, gmp_init("10000000", 10));

                                        $ts = gmp_div($ts, gmp_init("10000000", 10));

                                        $ts = gmp_strval($ts, 10);

                                        $ms = gmp_strval($ms, 10);

                                        $ts = gmdate('Y-m-d H:i:s', intval($ts))."'".str_pad($ms, 7/*0.1us*/, '0', STR_PAD_LEFT).' GMT';

                                        echo sprintf("%-32s %s\n", "Timestamp:", "[0x$timestamp] $ts");

                                        $x = hexdec(substr($uuid, 16, 4));

                                        $dec = $x & 0x3FFF; // The highest 2 bits are used by "variant" (10x)

                                        $hex = substr($uuid, 16, 4);

                                        echo sprintf("%-32s %s\n", "Clock ID:", "[0x$hex] $dec");

                                        $x = substr($uuid, 20, 12);

                                        $nodeid = '';

                                        for ($i=0; $i<6; $i++) {

                                                $nodeid .= substr($x, $i*2, 2);

                                                if ($i != 5) $nodeid .= '-';

                                        }

                                        $nodeid = strtoupper($nodeid);

                                        echo sprintf("%-32s %s\n", "Node ID:", "[0x$x] $nodeid");

                                        if (function_exists('decode_mac')) {

                                                echo "\nIn case that this Node ID is a MAC address, here is the interpretation of that MAC address:\n\n";

                                                decode_mac(strtoupper($nodeid));

                                        }

                                        break;

                                case 2:

                                        /*

                                        Variant 1, Version 2 UUID

                                        - 32 bit Local Domain Number

                                        - 16 bit Mid Time

                                        -  4 bit Version (fix 0x2)

                                        - 12 bit High Time

                                        -  2 bit Variant (fix 0b10)

                                        -  6 bit Clock Seq

                                        -  8 bit Local Domain

                                        - 48 bit MAC Address

                                        */

                                        // see also https://unicorn-utterances.com/posts/what-happened-to-uuid-v2

                                        echo sprintf("%-32s %s\n", "Version:", "[2] DCE Security version");

                                        # The clock_seq_low field (which represents an integer in the range [0, 28-1]) is interpreted as a local domain (as represented by sec_rgy_domain_t; see sec_rgy_domain_t ); that is, an identifier domain meaningful to the local host. (Note that the data type sec_rgy_domain_t can potentially hold values outside the range [0, 28-1]; however, the only values currently registered are in the range [0, 2], so this type mismatch is not significant.) In the particular case of a POSIX host, the value sec_rgy_domain_person is to be interpreted as the "POSIX UID domain", and the value sec_rgy_domain_group is to be interpreted as the "POSIX GID domain".

                                        $x = substr($uuid, 18, 2);

                                        if ($x == '00') $domain_info = 'Person (POSIX: User-ID)';

                                        else if ($x == '01') $domain_info = 'Group (POSIX: Group-ID)';

                                        else if ($x == '02') $domain_info = 'Organization';

                                        else $domain_info = 'site-defined (Domain '.hexdec($x).')';

                                        echo sprintf("%-32s %s\n", "Local Domain:", "[0x$x] $domain_info");

                                        # The time_low field (which represents an integer in the range [0, 232-1]) is interpreted as a local-ID; that is, an identifier (within the domain specified by clock_seq_low) meaningful to the local host. In the particular case of a POSIX host, when combined with a POSIX UID or POSIX GID domain in the clock_seq_low field (above), the time_low field represents a POSIX UID or POSIX GID, respectively.

                                        $x = substr($uuid, 0, 8);

                                        $dec = hexdec($x);

                                        echo sprintf("%-32s %s\n", "Local Domain Number:", "[0x$x] $dec");

                                        # Timestamp: Count of 100ns intervals since 15 Oct 1582 00:00:00

                                        # 1/0,0000001 = 10000000

                                        $timestamp = substr($uuid, 13, 3).substr($uuid, 8, 4).'00000000';

                                        $ts = gmp_init($timestamp, 16);

                                        $ts = gmp_sub($ts, gmp_init("122192928000000000", 10));

                                        $ms = gmp_mod($ts, gmp_init("10000000", 10));

                                        $ts = gmp_div($ts, gmp_init("10000000", 10));

                                        $ts = gmp_strval($ts, 10);

                                        $ms = gmp_strval($ms, 10);

                                        $ts_min = gmdate('Y-m-d H:i:s', intval($ts))."'".str_pad($ms, 7/*0.1us*/, '0', STR_PAD_LEFT).' GMT';

                                        $timestamp = substr($uuid, 13, 3).substr($uuid, 8, 4).'FFFFFFFF';

                                        $ts = gmp_init($timestamp, 16);

                                        $ts = gmp_sub($ts, gmp_init("122192928000000000", 10));

                                        $ms = gmp_mod($ts, gmp_init("10000000", 10));

                                        $ts = gmp_div($ts, gmp_init("10000000", 10));

                                        $ts = gmp_strval($ts, 10);

                                        $ms = gmp_strval($ms, 10);

                                        $ts_max = gmdate('Y-m-d H:i:s', intval($ts))."'".str_pad($ms, 7/*0.1us*/, '0', STR_PAD_LEFT).' GMT';

                                        $timestamp = substr($uuid, 13, 3).substr($uuid, 8, 4)/*.'xxxxxxxx'*/;

                                        echo sprintf("%-32s %s\n", "Timestamp:", "[0x$timestamp] $ts_min - $ts_max");

                                        $x = hexdec(substr($uuid, 16, 2));

                                        $dec = $x & 0x3F; // The highest 2 bits are used by "variant" (10xx)

                                        $hex = substr($uuid, 16, 2);

                                        echo sprintf("%-32s %s\n", "Clock ID:", "[0x$hex] $dec");

                                        $x = substr($uuid, 20, 12);

                                        $nodeid = '';

                                        for ($i=0; $i<6; $i++) {

                                                $nodeid .= substr($x, $i*2, 2);

                                                if ($i != 5) $nodeid .= '-';

                                        }

                                        $nodeid = strtoupper($nodeid);

                                        echo sprintf("%-32s %s\n", "Node ID:", "[0x$x] $nodeid");

                                        if (function_exists('decode_mac')) {

                                                echo "\nIn case that this Node ID is a MAC address, here is the interpretation of that MAC address:\n\n";

                                                decode_mac(strtoupper($nodeid));

                                        }

                                        break;

                                case 3:

                                        /*

                                        Variant 1, Version 3 UUID

                                        - 48 bit Hash High

                                        -  4 bit Version (fix 0x3)

                                        - 12 bit Hash Mid

                                        -  2 bit Variant (fix 0b10)

                                        - 62 bit Hash Low

                                        */

                                        echo sprintf("%-32s %s\n", "Version:", "[3] Name-based (MD5 hash)");

                                        $hash = str_replace('-', '', strtolower($uuid));

                                        $hash[12] = '?'; // was overwritten by version

                                        $var16a = dechex((hexdec($hash[16])&3) + 0x0/*00__*/);

                                        $var16b = dechex((hexdec($hash[16])&3) + 0x4/*01__*/);

                                        $var16c = dechex((hexdec($hash[16])&3) + 0x8/*10__*/);

                                        $var16d = dechex((hexdec($hash[16])&3) + 0xC/*11__*/);

                                        $hash[16] = '?'; // was partially overwritten by variant

                                        echo sprintf("%-32s %s\n", "MD5(Namespace+Subject):", "[0x$hash]");

                                        echo sprintf("%-32s %s\n", "", "                   ^");

                                        echo sprintf("%-32s %s\n", "", "                   $var16a, $var16b, $var16c, or $var16d");

                                        break;

                                case 4:

                                        /*

                                        Variant 1, Version 4 UUID

                                        - 48 bit Random High

                                        -  4 bit Version (fix 0x4)

                                        - 12 bit Random Mid

                                        -  2 bit Variant (fix 0b10)

                                        - 62 bit Random Low

                                        */

                                        echo sprintf("%-32s %s\n", "Version:", "[4] Random");

                                        $rand_line1 = '';

                                        $rand_line2 = '';

                                        for ($i=0; $i<16; $i++) {

                                                $bin = base_convert(substr($uuid, $i*2, 2), 16, 2);

                                                $bin = str_pad($bin, 8, "0", STR_PAD_LEFT);

                                                if ($i == 6) {

                                                        // was overwritten by version

                                                        $bin[0] = '?';

                                                        $bin[1] = '?';

                                                        $bin[2] = '?';

                                                        $bin[3] = '?';

                                                } else if ($i == 8) {

                                                        // was partially overwritten by variant

                                                        $bin[0] = '?';

                                                        $bin[1] = '?';

                                                }

                                                if ($i<8) $rand_line1 .= "$bin ";

                                                if ($i>=8) $rand_line2 .= "$bin ";

                                        }

                                        echo sprintf("%-32s %s\n", "Random bits:", trim($rand_line1));

                                        echo sprintf("%-32s %s\n", "",             trim($rand_line2));

                                        $rand_bytes = str_replace('-', '', strtolower($uuid));

                                        $rand_bytes[12] = '?'; // was overwritten by version

                                        $var16a = dechex((hexdec($rand_bytes[16])&3) + 0x0/*00__*/);

                                        $var16b = dechex((hexdec($rand_bytes[16])&3) + 0x4/*01__*/);

                                        $var16c = dechex((hexdec($rand_bytes[16])&3) + 0x8/*10__*/);

                                        $var16d = dechex((hexdec($rand_bytes[16])&3) + 0xC/*11__*/);

                                        $rand_bytes[16] = '?'; // was partially overwritten by variant

                                        echo sprintf("%-32s %s\n", "Random bytes:", "[0x$rand_bytes]");

                                        echo sprintf("%-32s %s\n", "", "                   ^");

                                        echo sprintf("%-32s %s\n", "", "                   $var16a, $var16b, $var16c, or $var16d");

                                        break;

                                case 5:

                                        /*

                                        Variant 1, Version 5 UUID

                                        - 48 bit Hash High

                                        -  4 bit Version (fix 0x5)

                                        - 12 bit Hash Mid

                                        -  2 bit Variant (fix 0b10)

                                        - 62 bit Hash Low

                                        */

                                        echo sprintf("%-32s %s\n", "Version:", "[5] Name-based (SHA-1 hash)");

                                        $hash = str_replace('-', '', strtolower($uuid));

                                        $hash[12] = '?'; // was overwritten by version

                                        $var16a = dechex((hexdec($hash[16])&3) + 0x0/*00__*/);

                                        $var16b = dechex((hexdec($hash[16])&3) + 0x4/*01__*/);

                                        $var16c = dechex((hexdec($hash[16])&3) + 0x8/*10__*/);

                                        $var16d = dechex((hexdec($hash[16])&3) + 0xC/*11__*/);

                                        $hash[16] = '?'; // was partially overwritten by variant

                                        $hash .= '????????'; // was cut off

                                        echo sprintf("%-32s %s\n", "SHA1(Namespace+Subject):", "[0x$hash]");

                                        echo sprintf("%-32s %s\n", "", "                   ^");

                                        echo sprintf("%-32s %s\n", "", "                   $var16a, $var16b, $var16c, or $var16d");

                                        break;

                                case 7:

                                        /*

                                        Variant 1, Version 7 UUID

                                        - 48 bit Unix Time in milliseconds

                                        -  4 bit Version (fix 0x7)

                                        - 12 bit Random

                                        -  2 bit Variant (fix 0b10)

                                        - 62 bit Random

                                        */

                                        echo sprintf("%-32s %s\n", "Version:", "[$version] Unix Epoch Time");

                                        $timestamp = substr($uuid, 0, 12);

                                        // Timestamp: Split into seconds and milliseconds

                                        $ts = gmp_init($timestamp, 16);

                                        $ms = gmp_mod($ts, gmp_init("1000", 10));

                                        $ts = gmp_div($ts, gmp_init("1000", 10));

                                        $ts = gmp_strval($ts, 10);

                                        $ms = gmp_strval($ms, 10);

                                        $ts = gmdate('Y-m-d H:i:s', intval($ts))."'".str_pad($ms, 3/*ms*/, '0', STR_PAD_LEFT).' GMT';

                                        echo sprintf("%-32s %s\n", "Timestamp:", "[0x$timestamp] $ts");

                                        $rand = '';

                                        for ($i=6; $i<16; $i++) {

                                                $bin = base_convert(substr($uuid, $i*2, 2), 16, 2);

                                                $bin = str_pad($bin, 8, "0", STR_PAD_LEFT);

                                                if ($i == 6) {

                                                        // was overwritten by version

                                                        $bin[0] = '?';

                                                        $bin[1] = '?';

                                                        $bin[2] = '?';

                                                        $bin[3] = '?';

                                                } else if ($i == 8) {

                                                        // was partially overwritten by variant

                                                        $bin[0] = '?';

                                                        $bin[1] = '?';

                                                }

                                                $rand .= "$bin ";

                                        }

                                        echo sprintf("%-32s %s\n", "Random bits:", trim($rand));

                                        $rand_bytes = substr(str_replace('-', '', strtolower($uuid)),13);

                                        $var16a = dechex((hexdec($rand_bytes[3])&3) + 0x0/*00__*/);

                                        $var16b = dechex((hexdec($rand_bytes[3])&3) + 0x4/*01__*/);

                                        $var16c = dechex((hexdec($rand_bytes[3])&3) + 0x8/*10__*/);

                                        $var16d = dechex((hexdec($rand_bytes[3])&3) + 0xC/*11__*/);

                                        $rand_bytes[3] = '?'; // was partially overwritten by variant

                                        echo sprintf("%-32s %s\n", "Random bytes:", "[0x$rand_bytes]");

                                        echo sprintf("%-32s %s\n", "", "      ^");

                                        echo sprintf("%-32s %s\n", "", "      $var16a, $var16b, $var16c, or $var16d");

                                        // TODO: convert to and from Base32 CROCKFORD ULID (make 2 methods in uuid_utils.inc.php)

                                        // e.g. ULID: 01GCZ05N3JFRKBRWKNGCQZGP44

                                        // "Be aware that all version 7 UUIDs may be converted to ULIDs but not all ULIDs may be converted to UUIDs."

                                        break;

                                case 8:

                                        /*

                                        Variant 1, Version 8 UUID

                                        - 48 bit Custom format

                                        -  4 bit Version (fix 0x8)

                                        - 12 bit Custom format

                                        -  2 bit Variant (fix 0b10)

                                        - 62 bit Custom format

                                        */

                                        echo sprintf("%-32s %s\n", "Version:", "[$version] Custom implementation");

                                        $custom_data = substr($uuid,0,12).substr($uuid,13); // exclude version nibble

                                        $custom_data[15] = dechex(hexdec($custom_data[15])&3); // nibble was partially overwritten by variant

                                        $custom_data = strtolower($custom_data);

                                        echo sprintf("%-32s %s\n", "Custom data:", "[0x$custom_data]");

                                        break;

                                default:

                                        echo sprintf("%-32s %s\n", "Version:", "[$version] Unknown");

                                        break;

                        }

                        break;

                case 2:

                        echo sprintf("%-32s %s\n", "Variant:", "[0b110] Reserved for Microsoft Corporation");

                        break;

                case 3:

                        echo sprintf("%-32s %s\n", "Variant:", "[0b111] Reserved for future use");

                        break;

        }

        if (!$echo) {

                $out = ob_get_contents();

                ob_end_clean();

                return $out;

        }

}

function uuid_canonize($uuid) {

        if (!uuid_valid($uuid)) return false;

        return oid_to_uuid(uuid_to_oid($uuid));

}

function oid_to_uuid($oid) {

        if (!is_uuid_oid($oid)) return false;

        if (substr($oid,0,1) == '.') {

                $oid = substr($oid, 1);

        }

        $ary = explode('.', $oid);

        if (!isset($ary[2])) return false;

        $val = $ary[2];

        $x = gmp_init($val, 10);

        $y = gmp_strval($x, 16);

        $y = str_pad($y, 32, "0", STR_PAD_LEFT);

        return substr($y,  0, 8).'-'.

               substr($y,  8, 4).'-'.

               substr($y, 12, 4).'-'.

               substr($y, 16, 4).'-'.

               substr($y, 20, 12);

}

function is_uuid_oid($oid, $only_allow_root=false) {

        if (substr($oid,0,1) == '.') $oid = substr($oid, 1); // remove leading dot

        $ary = explode('.', $oid);

        if ($only_allow_root) {

                if (count($ary) != 3) return false;

        } else {

                if (count($ary) < 3) return false;

        }