Skip to main content

Appendix B. Illustrative Examples

Appendix B. Illustrative Examples​

The following sections contain illustrative examples that serve to show how one may use UUIDv8 (Section 5.8) for custom and/or experimental application-based logic. The examples below have not been through the same rigorous testing, prototyping, and feedback loop that other algorithms in this document have undergone. The authors encourage implementers to create their own UUIDv8 algorithm rather than use the items defined in this section.

B.1. Example of a UUIDv8 Value (Time-Based)​

This example UUIDv8 test vector utilizes a well-known 64-bit Unix Epoch timestamp with 10 ns precision, truncated to the least significant, rightmost bits to fill the first 60 bits of custom_a and custom_b, while setting the version bits between these two segments to the version value of 8.

The variant bits are set; and the final segment, custom_c, is filled with random data.

Timestamp is Tuesday, February 22, 2022 2:22:22.000000 PM GMT-05:00, represented as 0x2489E9AD2EE2E00 or 164555774200000000 (10 ns-steps).

-------------------------------------------
field     bits value
-------------------------------------------
custom_a  48   0x2489E9AD2EE2
ver        4   0x8
custom_b  12   0xE00
var        2   0b10
custom_c  62   0b00, 0xEC932D5F69181C0
-------------------------------------------
total     128
-------------------------------------------
final: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0

Figure 27: UUIDv8 Example Time-Based Illustrative Example

B.2. Example of a UUIDv8 Value (Name-Based)​

As per Section 5.5, name-based UUIDs that want to use modern hashing algorithms MUST be created within the UUIDv8 space. These MAY leverage newer hashing algorithms such as SHA-256 or SHA-512 (as defined by [FIPS180-4]), SHA-3 or SHAKE (as defined by [FIPS202]), or even algorithms that have not been defined yet.

A SHA-256 version of the SHA-1 computation in Appendix A.4 is detailed in Figure 28 as an illustrative example detailing how this can be achieved. The creation of the name-based UUIDv8 value in this section follows the same logic defined in Section 5.5 with the difference being SHA-256 in place of SHA-1.

The field mapping and all values are illustrated in Figure 29. Finally, to further illustrate the bit swapping for version and variant and the unused/discarded part of the SHA-256 value, see Figure 30. An important note for secure hashing algorithms that produce outputs of an arbitrary size, such as those found in SHAKE, is that the output hash MUST be 128 bits or larger.

Namespace (DNS):       6ba7b810-9dad-11d1-80b4-00c04fd430c8
Name:                  www.example.com
----------------------------------------------------------------
SHA-256:
5c146b143c524afd938a375d0df1fbf6fe12a66b645f72f6158759387e51f3c8

Figure 28: UUIDv8 Example SHA256

-------------------------------------------
field     bits value
-------------------------------------------
custom_a  48   0x5c146b143c52
ver        4   0x8
custom_b  12   0xafd
var        2   0b10
custom_c  62   0b00, 0x38a375d0df1fbf6
-------------------------------------------
total     128
-------------------------------------------
final: 5c146b14-3c52-8afd-938a-375d0df1fbf6

Figure 29: UUIDv8 Example Name-Based SHA-256 Illustrative Example

A: 5c146b14-3c52-4afd-938a-375d0df1fbf6-fe12a66b645f72f6158759387e51f3c8
B: xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
C: 5c146b14-3c52-8afd-938a-375d0df1fbf6
D:                                     -fe12a66b645f72f6158759387e51f3c8

Figure 30: UUIDv8 Example Ver/Var Bit Swaps and Discarded SHA-256 Segment

Examining Figure 30:

  • Line A details the full SHA-256 as a hexadecimal value with the dashes inserted.

  • Line B details the version and variant hexadecimal positions, which must be overwritten.

  • Line C details the final value after the ver and var have been overwritten.

  • Line D details the discarded leftover values from the original SHA-256 computation.

Last updated on