php-uuid/docs/rfc4122/version2.rst

.. _rfc4122.version2:

=======================
Version 2: DCE Security
=======================

.. tip::

    DCE Security UUIDs are so-called because they were defined as part of the "Authentication and Security Services" for
    the `Distributed Computing Environment`_ (DCE) in the early 1990s.

    Version 2 UUIDs are not widely used. See :ref:`rfc4122.version2.problems` before deciding whether to use them.

Like a :ref:`version 1 UUID <rfc4122.version1>`, a version 2 UUID uses the current time, along with the MAC address (or
*node*) for a network interface on the local machine. Additionally, a version 2 UUID replaces the low part of the time
field with a local identifier such as the user ID or group ID of the local account that created the UUID. This serves
three purposes:

1. You can know *when* the identifier was created (see :ref:`rfc4122.version2.timestamp-problems`).
2. You can know *where* the identifier was created.
3. You can know *who* created the identifier.

In a distributed system, these three pieces of information can be valuable. Not only is there no need for a central
authority to generate identifiers, but you can determine what nodes in your infrastructure created the UUIDs, at what
time they were created, and the account on the machine that created them.

By default, ramsey/uuid will attempt to look up a MAC address for the machine it is running on, using this value as the
node. If it cannot find a MAC address, it will generate a random node.

.. code-block:: php
    :caption: Use a domain to generate a version 2, DCE Security UUID
    :name: rfc4122.version2.example

    use Ramsey\Uuid\Uuid;

    $uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_PERSON);

    printf(
        "UUID: %s\nVersion: %d\nDate: %s\nNode: %s\nDomain: %s\nID: %s\n",
        $uuid->toString(),
        $uuid->getFields()->getVersion(),
        $uuid->getDateTime()->format('r'),
        $uuid->getFields()->getNode()->toString(),
        $uuid->getLocalDomainName(),
        $uuid->getLocalIdentifier()->toString()
    );

This will generate a version 2 UUID and print out its string representation, the time the UUID was created, and the node
used to create it, as well as the name of the local domain specified and the local domain identifier (in this case, a
`POSIX`_ UID, automatically obtained from the local machine).

It will look something like this:

.. code-block:: text

    UUID: 000001f5-5e9a-21ea-9e00-0242ac130003
    Version: 2
    Date: Thu, 05 Mar 2020 04:30:10 +0000
    Node: 0242ac130003
    Domain: person
    ID: 501

Just as with version 1 UUIDs, you may provide custom values for version 2 UUIDs, including local identifier, node, and
clock sequence.

.. code-block:: php
    :caption: Provide custom identifier, node, and clock sequence to create a
              version 2, DCE Security UUID
    :name: rfc4122.version2.custom-example

    use Ramsey\Uuid\Provider\Node\StaticNodeProvider;
    use Ramsey\Uuid\Type\Hexadecimal;
    use Ramsey\Uuid\Type\Integer;
    use Ramsey\Uuid\Uuid;

    $localId = new Integer(1001);
    $nodeProvider = new StaticNodeProvider(new Hexadecimal('121212121212'));
    $clockSequence = 63;

    $uuid = Uuid::uuid2(
        Uuid::DCE_DOMAIN_ORG,
        $localId,
        $nodeProvider->getNode(),
        $clockSequence
    );

.. tip::

    Version 2 UUIDs generated in ramsey/uuid are instances of UuidV2. Check out the :php:class:`Ramsey\\Uuid\\Rfc4122\\UuidV2`
    API documentation to learn more about what you can do with a UuidV2 instance.

.. _rfc4122.version2.domains:

Domains
#######

The *domain* value tells what the local identifier represents.

If using the *person* or *group* domains, ramsey/uuid will attempt to look up these values from the local machine. On
`POSIX`_ systems, it will use ``id -u`` and ``id -g``, respectively. On Windows, it will use ``whoami`` and ``wmic``.

The *org* domain is site-defined. Its intent is to identify the organization that generated the UUID, but since this can
have different meanings for different companies and projects, you get to define its value.

.. list-table:: DCE Security Domains
    :widths: 30 70
    :align: center
    :header-rows: 1
    :name: rfc4122.version2.table-domains

    * - Constant
      - Description
    * - :php:const:`Uuid::DCE_DOMAIN_PERSON <Ramsey\\Uuid\\Uuid::DCE_DOMAIN_PERSON>`
      - The local identifier refers to a *person* (e.g., UID).
    * - :php:const:`Uuid::DCE_DOMAIN_GROUP <Ramsey\\Uuid\\Uuid::DCE_DOMAIN_GROUP>`
      - The local identifier refers to a *group* (e.g., GID).
    * - :php:const:`Uuid::DCE_DOMAIN_ORG <Ramsey\\Uuid\\Uuid::DCE_DOMAIN_ORG>`
      - The local identifier refers to an *organization* (this is site-defined).

.. note::

    According to section 5.2.1.1 of `DCE 1.1: Authentication and Security Services <https://publications.opengroup.org/c311>`_,
    the domain "can potentially hold values outside the range [0, 2\ :sup:`8` -- 1]; however, the only values currently
    registered are in the range [0, 2]."

    As a result, ramsey/uuid supports only the *person*, *group*, and *org* domains.

.. _rfc4122.version2.nodes:

Custom and Random Nodes
#######################

In the :ref:`example above <rfc4122.version2.custom-example>`, we provided a custom node when generating a version 2
UUID. You may also generate random node values.

To learn more, see the :ref:`rfc4122.version1.custom` and :ref:`rfc4122.version1.random` sections under
:ref:`rfc4122.version1`.

.. _rfc4122.version2.clock:

Clock Sequence
##############

In a version 2 UUID, the clock sequence serves the same purpose as in a version 1 UUID. See :ref:`rfc4122.version1.clock`
to learn more.

.. warning::

    The clock sequence in a version 2 UUID is a 6-bit number. It supports values from 0 to 63. This is different from
    the 14-bit number used by version 1 UUIDs.

    See :ref:`rfc4122.version2.uniqueness-problems` to understand how this affects version 2 UUIDs.

.. _rfc4122.version2.problems:

Problems With Version 2 UUIDs
#############################

Version 2 UUIDs can be useful for the data they contain. However, there are trade-offs in choosing to use them.

.. _rfc4122.version2.privacy-problems:

Privacy
-------

Unless using a randomly-generated node, version 2 UUIDs use the MAC address for a local hardware interface as the node
value. In addition, they use a local identifier --- usually an account or group ID. Some may consider the use of these
identifying features a breach of privacy. The use of a timestamp further complicates the issue, since these UUIDs could
be used to identify a user account on a specific machine at a specific time.

If you don't need an identifier with a local identifier and timestamp value embedded in it, see :ref:`rfc4122.version4`
to learn about random UUIDs.

.. _rfc4122.version2.uniqueness-problems:

Limited Uniqueness
------------------

With the inclusion of the local identifier and domain comes a serious limitation in the number of unique UUIDs that may
be created. This is because:

1. The local identifier replaces the lower 32 bits of the timestamp.
2. The domain replaces the lower 8 bits of the clock sequence.

As a result, the timestamp advances --- the clock *ticks* --- only once every 429.49 seconds (about 7 minutes). This
means the clock sequence is important to ensure uniqueness, but since the clock sequence is only 6 bits, compared to 14
bits for version 1 UUIDs, **only 64 unique UUIDs per combination of node, domain, and identifier may be generated per
7-minute tick of the clock**.

You can overcome this lack of uniqueness by using a :ref:`random node <rfc4122.version2.nodes>`, which provides 47 bits
of randomness to the UUID --- after setting the unicast/multicast bit (see discussion on :ref:`rfc4122.version1.custom`)
--- increasing the number of UUIDs per 7-minute clock tick to 2\ :sup:`53` (or 9,007,199,254,740,992), at the expense of
remaining locally unique.

.. note::

    This lack of uniqueness did not present a problem for DCE, since:

        [T]he security architecture of DCE depends upon the uniqueness of security-version UUIDs *only within the
        context of a cell*; that is, only within the context of the local [Registration Service's] (persistent)
        datastore, and that degree of uniqueness can be guaranteed by the RS itself (namely, the RS maintains state in
        its datastore, in the sense that it can always check that every UUID it maintains is different from all other
        UUIDs it maintains). In other words, while security-version UUIDs are (like all UUIDs) specified to be "globally
        unique in space and time", security is not compromised if they are merely "locally unique per cell".

        -- `DCE 1.1: Authentication and Security Services, section 5.2.1.1 <https://publications.opengroup.org/c311>`_

.. _rfc4122.version2.timestamp-problems:

Lossy Timestamps
----------------

Version 2 UUIDs are generated in the same way as version 1 UUIDs, but the low part of the timestamp (the ``time_low``
field) is replaced by a 32-bit integer that represents a local identifier. Because of this, not only do version 2 UUIDs
have :ref:`limited uniqueness <rfc4122.version2.uniqueness-problems>`, but they also lack time precision.

When reconstructing the timestamp to return a `DateTimeInterface`_ instance from :php:meth:`UuidV2::getDateTime()
<Ramsey\\Uuid\\Rfc4122\\UuidV2::getDateTime>`, we replace the 32 lower bits of the timestamp with zeros, since the local
identifier should not be part of the timestamp. This results in a loss of precision, causing the timestamp to be off by
a range of 0 to 429.4967295 seconds (or 7 minutes, 9 seconds, and 496,730 microseconds).

When using version 2 UUIDs, treat the timestamp as an approximation. At worst, it could be off by about 7 minutes.

.. hint::

    If the value 429.4967295 looks familiar, it's because it directly corresponds to 2\ :sup:`32` -- 1, or ``0xffffffff``.
    The local identifier is 32-bits, and we have set each of these bits to 0, so the maximum range of timestamp drift is
    ``0x00000000`` to ``0xffffffff`` (counted in 100-nanosecond intervals).

.. _Distributed Computing Environment: https://en.wikipedia.org/wiki/Distributed_Computing_Environment
.. _POSIX: https://en.wikipedia.org/wiki/POSIX
.. _DateTimeInterface: https://www.php.net/datetimeinterface