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 Problems With Version 2 UUIDs before deciding whether to use them.

Like a version 1 UUID, 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 Lossy Timestamps).

  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.

Use a domain to generate a version 2, DCE Security UUID
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()?->value,
    $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:

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.

Provide custom identifier, node, and clock sequence to create a version 2, DCE Security UUID
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 Ramsey\Uuid\Rfc4122\UuidV2 API documentation to learn more about what you can do with a UuidV2 instance.

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.

DCE Security Domains

Constant

Description

Uuid::DCE_DOMAIN_PERSON

The local identifier refers to a person (e.g., UID).

Uuid::DCE_DOMAIN_GROUP

The local identifier refers to a group (e.g., GID).

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, the domain “can potentially hold values outside the range [0, 28 – 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.

Custom and Random Nodes

In the example above, we provided a custom node when generating a version 2 UUID. You may also generate random node values.

To learn more, see the Providing a Custom Node and Generating a Random Node sections under Version 1: Gregorian Time.

Clock Sequence

In a version 2 UUID, the clock sequence serves the same purpose as in a version 1 UUID. See What’s a Clock Sequence? 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 Limited Uniqueness to understand how this affects version 2 UUIDs.

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.

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 Version 4: Random to learn about random UUIDs.

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 random node, which provides 47 bits of randomness to the UUID — after setting the unicast/multicast bit (see discussion on Providing a Custom Node) — increasing the number of UUIDs per 7-minute clock tick to 253 (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

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 limited uniqueness, but they also lack time precision.

When reconstructing the timestamp to return a DateTimeInterface instance from 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 232 – 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).