uuid

Draft Community Group Report

Latest published version:
https://www.w3.org/TR/uuid/
Latest editor's draft:
https://wicg.github.io/uuid/
Editors:
Ben Coe (Google)
Robert Kieffer
Christoph Tavan (Google)

Copyright © 2021 the Contributors to the uuid Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Abstract

This specification describes an API for generating character encoded Universally Unique Identifiers (UUID) based on [RFC4122], available as a method on the Crypto interface.

Status of This Document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

This is a work in progress.

GitHub Issues are preferred for discussion of this specification.

1. Goals

Provide a straightforward and secure mechanism for generating UUIDs that addresses developers' common needs (identifiers for generated pages, identifiers for sessions, identifiers for generated HTML elements, database keys, etc.), while minimizing the amount of domain knowledge a developer requires to discover and use the feature.

2. Usage Example

To generate a UUID, simply call Crypto's randomUUID() method:

Example 1: Generate unique name for download 
const filename = `${crypto.randomUUID()}.txt`;
// do something with filename.

3. Extensions to the Crypto interface 

WebIDL[Exposed=(Window,Worker)]
partial interface Crypto {
  [SecureContext] DOMString randomUUID();
};
Note

3.1 The randomUUID() method

The randomUUID() method steps are to return the result of generating a random UUID.

4. Generating a random UUID

To generate a random UUID:

  1. Let bytes be a list with 16 elements of the type byte.
  2. Fill bytes with cryptographically secure random bytes.
  3. Set the 4 most significant bits of bytes[6], which represent the UUID version, to 0b0100.
  4. Set the 2 most significant bits of bytes[8], which represent the UUID variant, to 0b10.

  5. Return the concatenation of «

    1. hexadecimal representation of bytes[0], hexadecimal representation of bytes[1], hexadecimal representation of bytes[2], hexadecimal representation of bytes[3],
    2. "-",
    3. hexadecimal representation of bytes[4], hexadecimal representation of bytes[5],
    4. "-",
    5. hexadecimal representation of bytes[6], hexadecimal representation of bytes[7],
    6. "-",
    7. hexadecimal representation of bytes[8], hexadecimal representation of bytes[9],
    8. "-",
    9. hexadecimal representation of bytes[10], hexadecimal representation of bytes[11], hexadecimal representation of bytes[12], hexadecimal representation of bytes[13], hexadecimal representation of bytes[14], hexadecimal representation of bytes[15]

    ».

For the steps described in the algorithm to generate a random UUID, the hexadecimal representation of a byte value is the two-character string created by expressing value in hexadecimal using ASCII lower hex digits, left-padded with "0" to reach two ASCII lower hex digits.

5. Security considerations

This section is non-normative.

Denial of service
Generating random values has the potential to perform computationally expensive and/or blocking work (if there is not enough entropy available in the system). As such, hostile applications may attempt to misuse this API and attempt to cause significant amount of work to be performed by an implementation, denying access or services to other applications that are executing. In practice, these concerns can be mitigated by using non-blocking sources of randomness, e.g., "/dev/urandom". See also, WebCrypto Security Considerations.
Insufficient entropy
If randomUUID() is invoked before the underlying system is seeded with enough entropy it may result in colliding UUIDs (due to cycles in the PRNG). Authors of applications that use randomUUID need to be aware of these risks.

6. Privacy considerations

This section is non-normative.

Fingerprinting
By exposing additional APIs that reflect capabilities of the underlying platform, this specification may allow malicious applications to determine or distinguish different user agents or devices. One such approach is outlined in Clock Around the Clock: Time-Based Device Fingerprinting which discusses creating a fingerprint based on a PRNG in JavaScript. randomUUID is not likely to make users more susceptible to fingerprinting than they are through existing cryptography methods. See also, WebCrypto Privacy Considerations.
Use of randomUUID as user ID
randomUUID is useful for generating user IDs, but does not directly give any ability to generate global identifiers.

7. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

A. References

A.1 Normative references

[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC4122]
A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4122
[WebCryptoAPI]
Web Cryptography API. Mark Watson. W3C. 26 January 2017. W3C Recommendation. URL: https://www.w3.org/TR/WebCryptoAPI/
[webidl]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

A.2 Informative references

[RFC2141]
URN Syntax. R. Moats. IETF. May 1997. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc2141