idnits 2.17.1 draft-peabody-dispatch-new-uuid-format-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC4122]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The draft header indicates that this document updates RFC4122, but the abstract doesn't seem to directly say this. It does mention RFC4122 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: MAC addresses pose inherent security risks and MUST not be used for node generation. As such they have been strictly forbidden from time-based UUIDs within this specification. Instead pseudo-random bits SHOULD selected from a source with sufficient entropy to ensure guaranteed uniqueness among UUID generation. (Using the creation date from RFC4122, updated by this document, for RFC5378 checks: 2002-09-23) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (26 April 2021) is 1093 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 dispatch BGP. Peabody 3 Internet-Draft 4 Updates: 4122 (if approved) K. Davis 5 Intended status: Standards Track 26 April 2021 6 Expires: 28 October 2021 8 New UUID Formats 9 draft-peabody-dispatch-new-uuid-format-01 11 Abstract 13 This document presents new time-based UUID formats which are suited 14 for use as a database key. 16 A common case for modern applications is to create a unique 17 identifier for use as a primary key in a database table. This 18 identifier usually implements an embedded timestamp that is sortable 19 using the monotonic creation time in the most significant bits. In 20 addition the identifier is highly collision resistant, difficult to 21 guess, and provides minimal security attack surfaces. None of the 22 existing UUID versions, including UUIDv1, fulfill each of these 23 requirements in the most efficient possible way. This document is a 24 proposal to update [RFC4122] with three new UUID versions that 25 address these concerns, each with different trade-offs. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 28 October 2021. 44 Copyright Notice 46 Copyright (c) 2021 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Simplified BSD License text 55 as described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Summary of Changes . . . . . . . . . . . . . . . . . . . . . 5 63 4. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 4.1. Versions . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4.2. Variant . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 4.3. UUIDv6 Layout and Bit Order . . . . . . . . . . . . . . . 7 67 4.3.1. UUIDv6 Timestamp Usage . . . . . . . . . . . . . . . 8 68 4.3.2. UUIDv6 Clock Sequence Usage . . . . . . . . . . . . . 8 69 4.3.3. UUIDv6 Node Usage . . . . . . . . . . . . . . . . . . 8 70 4.3.4. UUIDv6 Basic Creation Algorithm . . . . . . . . . . . 8 71 4.4. UUIDv7 Layout and Bit Order . . . . . . . . . . . . . . . 10 72 4.4.1. UUIDv7 Timestamp Usage . . . . . . . . . . . . . . . 11 73 4.4.2. UUIDv7 Clock Sequence Usage . . . . . . . . . . . . . 11 74 4.4.3. UUIDv7 Node Usage . . . . . . . . . . . . . . . . . . 11 75 4.4.4. UUIDv7 Encoding and Decoding . . . . . . . . . . . . 11 76 4.5. UUIDv8 Layout and Bit Order . . . . . . . . . . . . . . . 16 77 4.5.1. UUIDv8 Timestamp Usage . . . . . . . . . . . . . . . 18 78 4.5.2. UUIDv8 Clock Sequence Usage . . . . . . . . . . . . . 20 79 4.5.3. UUIDv8 Node Usage . . . . . . . . . . . . . . . . . . 20 80 4.5.4. UUIDv6 Basic Creation Algorithm . . . . . . . . . . . 21 81 5. Encoding and Storage . . . . . . . . . . . . . . . . . . . . 24 82 6. Global Uniqueness . . . . . . . . . . . . . . . . . . . . . . 24 83 7. Distributed UUID Generation . . . . . . . . . . . . . . . . . 24 84 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 85 9. Security Considerations . . . . . . . . . . . . . . . . . . . 25 86 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 25 87 11. Normative References . . . . . . . . . . . . . . . . . . . . 25 88 12. Informative References . . . . . . . . . . . . . . . . . . . 26 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 91 1. Introduction 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 95 document are to be interpreted as described in [RFC2119]. 97 2. Background 99 A lot of things have changed in the time since UUIDs were originally 100 created. Modern applications have a need to use (and many have 101 already implemented) UUIDs as database primary keys. 103 The motivation for using UUIDs as database keys stems primarily from 104 the fact that applications are increasingly distributed in nature. 105 Simplistic "auto increment" schemes with integers in sequence do not 106 work well in a distributed system since the effort required to 107 synchronize such numbers across a network can easily become a burden. 108 The fact that UUIDs can be used to create unique and reasonably short 109 values in distributed systems without requiring synchronization makes 110 them a good candidate for use as a database key in such environments. 112 However some properties of [RFC4122] UUIDs are not well suited to 113 this task. First, most of the existing UUID versions such as UUIDv4 114 have poor database index locality. Meaning new values created in 115 succession are not close to each other in the index and thus require 116 inserts to be performed at random locations. The negative 117 performance effects of which on common structures used for this 118 (B-tree and its variants) can be dramatic. As such newly inserted 119 values SHOULD be time-ordered to address this. 121 While it is true that UUIDv1 does contain an embedded timestamp and 122 can be time-ordered; UUIDv1 has other issues. It is possible to sort 123 Version 1 UUIDs by time but it is a laborious task. The process 124 requires breaking the bytes of the UUID into various pieces, re- 125 ordering the bits, and then determining the order from the 126 reconstructed timestamp. This is not efficient in very large 127 systems. Implementations would be simplified with a sort order where 128 the UUID can simply be treated as an opaque sequence of bytes and 129 ordered as such. 131 After the embedded timestamp, the remaining 64 bits are in essence 132 used to provide uniqueness both on a global scale and within a given 133 timestamp tick. The clock sequence value ensures that when multiple 134 UUIDs are generated for the same timestamp value are given a 135 monotonic sequence value. This explicit sequencing helps further 136 facilitate sorting. The remaining random bits ensure collisions are 137 minimal. 139 Furthermore, UUIDv1 utilizes a non-standard timestamp epoch derived 140 from the Gregorian Calendar. More specifically, the Coordinated 141 Universal Time (UTC) as a count of 100-nanosecond intervals since 142 00:00:00.00, 15 October 1582. Implementations and many languages may 143 find it easier to implement the widely adopted and well known Unix 144 Epoch, a custom epoch, or another timestamp source with various 145 levels of timestamp precision required by the application. 147 Lastly, privacy and network security issues arise from using a MAC 148 address in the node field of Version 1 UUIDs. Exposed MAC addresses 149 can be used as an attack surface to locate machines and reveal 150 various other information about such machines (minimally 151 manufacturer, potentially other details). Instead "cryptographically 152 secure" pseudo-random number generators (CSPRNGs) or pseudo-random 153 number generators (PRNG) SHOULD be used within an application context 154 to provide uniqueness and unguessability. 156 Due to the shortcomings of UUIDv1 and UUIDv4 details so far, many 157 widely distributed database applications and large application 158 vendors have sought to solve the problem of creating a better time- 159 based, sortable unique identifier for use as a database key. This 160 has lead to numerous implementations over the past 10+ years solving 161 the same problem in slightly different ways. 163 While preparing this specification the following 16 different 164 implementations were analyzed for trends in total ID length, bit 165 Layout, lexical formatting/encoding, timestamp type, timestamp 166 format, timestamp accuracy, node format/components, collision 167 handling and multi-timestamp tick generation sequencing. 169 1. [LexicalUUID] by Twitter 170 2. [Snowflake] by Twitter 171 3. [Flake] by Boundary 172 4. [ShardingID] by Instagram 173 5. [KSUID] by Segment 174 6. [Elasticflake] by P. Pearcy 175 7. [FlakeID] by T. Pawlak 176 8. [Sonyflake] by Sony 177 9. [orderedUuid] by IT. Cabrera 178 10. [COMBGUID] by R. Tallent 179 11. [ULID] by A. Feerasta 180 12. [SID] by A. Chilton 181 13. [pushID] by Google 182 14. [XID] by O. Poitrey 183 15. [ObjectID] by MongoDB 184 16. [CUID] by E. Elliott 185 An inspection of these implementations details the following trends 186 that help define this standard: 188 - Timestamps MUST be k-sortable. That is, values within or close 189 to the same timestamp are ordered properly by sorting algorithms. 190 - Timestamps SHOULD be big-endian with the most-significant bits 191 of the time embedded as-is without reordering. 192 - Timestamps SHOULD utilize millisecond precision and Unix Epoch 193 as timestamp source. Although, there is some variation to this 194 among implementations depending on the application requirements. 195 - The ID format SHOULD be Lexicographically sortable while in the 196 textual representation. 197 - IDs MUST ensure proper embedded sequencing to facilitate sorting 198 when multiple UUIDs are created during a given timestamp. 199 - IDs MUST NOT require unique network identifiers as part of 200 achieving uniqueness. 201 - Distributed nodes MUST be able to create collision resistant 202 Unique IDs without a consulting a centralized resource. 204 3. Summary of Changes 206 In order to solve these challenges this specification introduces 207 three new version identifiers assigned for time-based UUIDs. 209 The first, UUIDv6, aims to be the easiest to implement for 210 applications which already implement UUIDv1. The UUIDv6 211 specification keeps the original Gregorian timestamp source but does 212 not reorder the timestamp bits as per the process utilized by UUIDv1. 213 UUIDv6 also requires that pseudo-random data MUST be used in place of 214 the MAC address. The rest of the UUIDv1 format remains unchanged in 215 UUIDv6. See Section 4.3 217 Next, UUIDv7 introduces an entirely new time-based UUID bit layout 218 utilizing a variable length timestamp sourced from the widely 219 implemented and well known Unix Epoch timestamp source. The 220 timestamp is broken into a 36-bit integer sections part, and is 221 followed by a field of variable length which represents the sub- 222 second timestamp portion, encoded so that each bit from most to least 223 significant adds more precision. See Section 4.4 225 Finally, UUIDv8 introduces a relaxed time-based UUID format that 226 caters to application implementations that cannot utilize UUIDv1, 227 UUIDv6, or UUIDv7. UUIDv8 also future-proofs this specification by 228 allowing time-based UUID formats from timestamp sources that are not 229 yet be defined. The variable size timestamp offers lots of 230 flexibility to create an implementation specific RFC compliant time- 231 based UUID while retaining the properties that make UUID great. See 232 Section 4.5 234 4. Format 236 The UUID length of 16 octets (128 bits) remains unchanged. The 237 textual representation of a UUID consisting of 36 hexadecimal and 238 dash characters in the format 8-4-4-4-12 remains unchanged for human 239 readability. In addition the position of both the Version and 240 Variant bits remain unchanged in the layout. 242 4.1. Versions 244 Table 1 defines the 4-bit version found in Bits 48 through 51 within 245 a given UUID. 247 +------+------+------+------+---------+-----------------------+ 248 | Msb0 | Msb1 | Msb2 | Msb3 | Version | Description | 249 +------+------+------+------+---------+-----------------------+ 250 | 0 | 1 | 1 | 0 | 6 | Reordered Gregorian | 251 | | | | | | time-based UUID | 252 +------+------+------+------+---------+-----------------------+ 253 | 0 | 1 | 1 | 1 | 7 | Variable length Unix | 254 | | | | | | Epoch time-based UUID | 255 +------+------+------+------+---------+-----------------------+ 256 | 1 | 0 | 0 | 0 | 8 | Custom time-based | 257 | | | | | | UUID | 258 +------+------+------+------+---------+-----------------------+ 260 Table 1: UUID versions defined by this specification 262 4.2. Variant 264 The variant bits utilized by UUIDs in this specification remains the 265 same as [RFC4122], Section 4.1.1. 267 The Table 2 lists the contents of the variant field, bits 64 and 65, 268 where the letter "x" indicates a "don't-care" value. Common hex 269 values of 8 (1000), 9 (1001), A (1010), and B (1011) frequent the 270 text representation. 272 +------+------+------+-----------------------------------------+ 273 | Msb0 | Msb1 | Msb2 | Description | 274 +------+------+------+-----------------------------------------+ 275 | 1 | 0 | x | The variant specified in this document. | 276 +------+------+------+-----------------------------------------+ 278 Table 2: UUID Variant defined by this specification 280 4.3. UUIDv6 Layout and Bit Order 282 UUIDv6 aims to be the easiest to implement by reusing most of the 283 layout of bits found in UUIDv1 but with changes to bit ordering for 284 the timestamp. Where UUIDv1 splits the timestamp bits into three 285 distinct parts and orders them as time_low, time_mid, 286 time_high_and_version. UUIDv6 instead keeps the source bits from the 287 timestamp intact and changes the order to time_high, time_mid, and 288 time_low. Incidentally this will match the original 60-bit Gregorian 289 timestamp source. The clock sequence bits remain unchanged from 290 their usage and position in [RFC4122]. The 48-bit node MUST be set 291 to a pseudo-random value. 293 The format for the 16-octet, 128-bit UUIDv6 is shown in Figure 1 295 0 1 2 3 296 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 297 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 298 | time_high | 299 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 300 | time_mid | time_low_and_version | 301 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 302 |clk_seq_hi_res | clk_seq_low | node (0-1) | 303 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 304 | node (2-5) | 305 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 307 Figure 1: UUIDv6 Field and Bit Layout 309 time_high: 310 The most significant 32 bits of the 60-bit starting timestamp. 311 Occupies bits 0 through 31 (octets 0-3) 313 time_mid: 314 The middle 16 bits of the 60-bit starting timestamp. Occupies 315 bits 32 through 47 (octets 4-5) 317 time_low_and_version: 318 The first four most significant bits MUST contain the UUIDv6 319 version (0110) while the remaining 12 bits will contain the least 320 significant 12 bits from the 60-bit starting timestamp. Occupies 321 bits 48 through 63 (octets 6-7) 323 clk_seq_hi_res: 324 The first two bits MUST be set to the UUID variant (10) The 325 remaining 6 bits contain the high portion of the clock sequence. 326 Occupies bits 64 through 71 (octet 8) 328 clock_seq_low: 329 The 8 bit low portion of the clock sequence. Occupies bits 72 330 through 79 (octet 9) 332 node: 333 48-bit pseudo-random number used as a spatially unique identifier 334 Occupies bits 80 through 127 (octets 10-15) 336 4.3.1. UUIDv6 Timestamp Usage 338 UUIDv6 reuses the 60-bit Gregorian timestamp with 100-nanosecond 339 precision defined in [RFC4122], Section 4.1.4. 341 4.3.2. UUIDv6 Clock Sequence Usage 343 UUIDv6 makes no change to the Clock Sequence usage defined by 344 [RFC4122], Section 4.1.5. 346 4.3.3. UUIDv6 Node Usage 348 UUIDv6 node bits SHOULD be set to a 48-bit random or pseudo-random 349 number. UUIDv6 nodes SHOULD NOT utilize an IEEE 802 MAC address or 350 the [RFC4122], Section 4.5 method of generating a random multicast 351 IEEE 802 MAC address. 353 4.3.4. UUIDv6 Basic Creation Algorithm 355 The following implementation algorithm is based on [RFC4122] but with 356 changes specific to UUIDv6: 358 1. From a system-wide shared stable store (e.g., a file) or global 359 variable, read the UUID generator state: the values of the 360 timestamp and clock sequence used to generate the last UUID. 362 2. Obtain the current time as a 60-bit count of 100-nanosecond 363 intervals since 00:00:00.00, 15 October 1582. 365 3. Set the time_low field to the 12 least significant bits of the 366 starting 60-bit timestamp. 368 4. Truncate the timestamp to the 48 most significant bits in order 369 to create time_high_and_time_mid. 371 5. Set the time_high field to the 32 most significant bits of the 372 truncated timestamp. 374 6. Set the time_mid field to the 16 least significant bits of the 375 truncated timestamp. 377 7. Create the 16-bit time_low_and_version by concatenating the 378 4-bit UUIDv6 version with the 12-bit time_low. 380 8. If the state was unavailable (e.g., non-existent or corrupted) 381 or the timestamp is greater than the current timestamp generate 382 a random 14-bit clock sequence value. 384 9. If the state was available, but the saved timestamp is less than 385 or equal to the current timestamp, increment the clock sequence 386 value. 388 10. Complete the 16-bit clock sequence high, low and reserved 389 creation by concatenating the clock sequence onto UUID variant 390 bits which take the most significant position in the 16-bit 391 value. 393 11. Generate a 48-bit psuedo-random node. 395 12. Format by concatenating the 128 bits from each parts: 396 time_high|time_mid|time_low_and_version|variant_clk_seq|node 398 13. Save the state (current timestamp and clock sequence) back to 399 the stable store 401 The steps for splitting time_high_and_time_mid into time_high and 402 time_mid are optional since the 48-bits of time_high and time_mid 403 will remain in the same order as time_high_and_time_mid during the 404 final concatenation. This extra step of splitting into the most 405 significant 32 bits and least significant 16 bits proves useful when 406 reusing an existing UUIDv1 implementation. In which the following 407 logic can be applied to reshuffle the bits with minimal 408 modifications. 410 +--------------+------+--------------+ 411 | UUIDv1 Field | Bits | UUIDv6 Field | 412 +--------------+------+--------------+ 413 | time_low | 32 | time_high | 414 +--------------+------+--------------+ 415 | time_mid | 16 | time_mid | 416 +--------------+------+--------------+ 417 | time_high | 12 | time_low | 418 +--------------+------+--------------+ 420 Table 3: UUIDv1 to UUIDv6 Field 421 Mappings 423 4.4. UUIDv7 Layout and Bit Order 425 The UUIDv7 format is designed to encode a Unix timestamp with 426 arbitrary sub-second precision. The key property provided by UUIDv7 427 is that timestamp values generated by one system and parsed by 428 another are guaranteed to have sub-section precision of either the 429 generator or the parser, whichever is less. Additionally, the system 430 parsing the UUIDv7 value does not need to know which precision was 431 used during encoding in order to function correctly. 433 The format for the 16-octet, 128-bit UUIDv6 is shown in Figure 2 435 0 1 2 3 436 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 437 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 438 | unixts | 439 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 440 |unixts | subsec_a | ver | subsec_b | 441 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 442 |var| subsec_seq_node | 443 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 444 | subsec_seq_node | 445 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 447 Figure 2: UUIDv7 Field and Bit Layout 449 unixts: 450 36-bit big-endian unsigned Unix Timestamp value 452 subsec_a: 453 12-bits allocated to sub-section precision values. 455 ver: 456 The 4 bit UUIDv8 version (0111) 458 subsec_b: 459 12-bits allocated to sub-section precision values. 461 var: 462 2-bit UUID variant (10) 464 subsec_seq_node: 465 The remaining 62 bits which MAY be allocated to any combination of 466 additional sub-section precision, sequence counter, or pseudo- 467 random data. 469 4.4.1. UUIDv7 Timestamp Usage 471 UUIDv7 utilizes a 36-bit big-endian unsigned Unix Timestamp value 472 (number of seconds since the epoch of 1 Jan 1970, leap seconds 473 excluded so each hour is exactly 3600 seconds long). 475 Additional sub-second precision (millisecond, nanosecond, 476 microsecond, etc) MAY be provided for encoding and decoding in the 477 remaining bits in the layout. 479 4.4.2. UUIDv7 Clock Sequence Usage 481 UUIDv7 SHOULD utilize a motonic sequence counter to provide 482 additional sequencing guarantees when multiple UUIDv7 values are 483 created in the same UNIXTS and SUBSEC timestamp. The amount of bits 484 allocates to the sequence counter depend on the precision of the 485 timestamp. For example, a more accurate timestamp source using 486 nanosecond precision will require less clock sequence bits than a 487 timestamp source utilizing seconds for precision. For best 488 sequencing results the sequence counter SHOULD be placed immediately 489 after available sub-second bits. 491 The clock sequence MUST start at zero and increment monotonically for 492 each new UUID created on by the application on the same timestamp. 493 When the timestamp increments the clock sequence MUST be reset to 494 zero. The clock sequence MUST NOT rollover or reset to zero unless 495 the timestamp has incremented. Care MUST be given to ensure that an 496 adequate sized clock sequence is selected for a given application 497 based on expected timestamp precision and expected UUID generation 498 rates. 500 4.4.3. UUIDv7 Node Usage 502 UUIDv7 implementations, even with very detailed sub-second precision 503 and the optional sequence counter, MAY have leftover bits that will 504 be identified as the Node for this section. The UUIDv7 Node MAY 505 contain any set of data an implementation desires however the node 506 MUST NOT be set to all 0s which does not ensure global uniqueness. 507 In most scenarios the node SHOULD be filled with pseudo-random data. 509 4.4.4. UUIDv7 Encoding and Decoding 511 The UUIDv7 bit layout for encoding and decoding are described 512 separately in this document. 514 4.4.4.1. UUIDv7 Encoding 516 Since the UUIDv7 Unix timestamp is fixed at 36 bits in length the 517 exact layout for encoding UUIDv7 depends on the precision (number of 518 bits) used for the sub-second portion and the sizes of the optionally 519 desired sequence counter and node bits. 521 Three examples of UUIDv7 encoding are given below as a general 522 guidelines but implementations are not limited to just these three 523 examples. 525 All of these fields are only used during encoding, and during 526 decoding the system is unaware of the bit layout used for them and 527 considers this information opaque. As such, implementations 528 generating these values can assign whatever lengths to each field it 529 deems applicable, as long as it does not break decoding compatibility 530 (i.e. Unix timestamp (unixts), version (ver) and variant (var) have 531 to stay where they are, and clock sequence counter (seq), random 532 (random) or other implementation specific values must follow the sub- 533 second encoding). 535 In Figure 3 the UUIDv7 has been created with millisecond precision 536 with the available sub-second precision bits. 538 Examining Figure 3 one can observe: 540 * The first 36 bits have been dedicated to the Unix Timestamp 541 (unixts) 543 * All 12 bits of scenario subsec_a is fully dedicated to millisecond 544 information (msec). 546 * The 4 Version bits remain unchanged (ver). 548 * All 12 bits of subsec_b have been dedicated to a motonic clock 549 sequence counter (seq). 551 * The 2 Variant bits remain unchanged (var). 553 * Finally the remaining 62 bits in the subsec_seq_node section are 554 layout is filled out with random data to pad the length and 555 provide guaranteed uniqueness (rand). 557 0 1 2 3 558 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 559 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 560 | unixts | 561 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 562 |unixts | msec | ver | seq | 563 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 564 |var| rand | 565 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 566 | rand | 567 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 569 Figure 3: UUIDv7 Field and Bit Layout - Encoding Example (Millisecond 570 Precision) 572 In Figure 4 the UUIDv7 has been created with Microsecond precision 573 with the available sub-second precision bits. 575 Examining Figure 4 one can observe: 577 * The first 36 bits have been dedicated to the Unix Timestamp 578 (unixts) 580 * All 12 bits of scenario subsec_a is fully dedicated to providing 581 sub-second encoding for the Microsecond precision (usec). 583 * The 4 Version bits remain unchanged (ver). 585 * All 12 bits of subsec_b have been dedicated to providing sub- 586 second encoding for the Microsecond precision (usec). 588 * The 2 Variant bits remain unchanged (var). 590 * A 14 bit motonic clock sequence counter (seq) has been embedded in 591 the most significant position of subsec_seq_node 593 * Finally the remaining 48 bits in the subsec_seq_node section are 594 layout is filled out with random data to pad the length and 595 provide guaranteed uniqueness (rand). 597 0 1 2 3 598 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 599 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 600 | unixts | 601 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 602 |unixts | usec | ver | usec | 603 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 604 |var| seq | rand | 605 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 606 | rand | 607 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 609 Figure 4: UUIDv7 Field and Bit Layout - Encoding Example (Microsecond 610 Precision) 612 In Figure 5 the UUIDv7 has been created with Nanosecond precision 613 with the available sub-second precision bits. 615 Examining Figure 5 one can observe: 617 * The first 36 bits have been dedicated to the Unix Timestamp 618 (unixts) 620 * All 12 bits of scenario subsec_a is fully dedicated to providing 621 sub-second encoding for the Nanosecond precision (nsec). 623 * The 4 Version bits remain unchanged (ver). 625 * All 12 bits of subsec_b have been dedicated to providing sub- 626 second encoding for the Nanosecond precision (nsec). 628 * The 2 Variant bits remain unchanged (var). 630 * The first 14 bit of the subsec_seq_node dedicated to providing 631 sub-second encoding for the Nanosecond precision (nsec). 633 * The next 8 bits of subsec_seq_node dedicated a motonic clock 634 sequence counter (seq). 636 * Finally the remaining 40 bits in the subsec_seq_node section are 637 layout is filled out with random data to pad the length and 638 provide guaranteed uniqueness (rand). 640 0 1 2 3 641 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 642 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 643 | unixts | 644 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 645 |unixts | nsec | ver | nsec | 646 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 647 |var| nsec | seq | rand | 648 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 649 | rand | 650 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 652 Figure 5: UUIDv7 Field and Bit Layout - Encoding Example 653 (Nanosecond Precision) 655 4.4.4.2. UUIDv7 Decoding 657 When decoding or parsing a UUIDv7 value there are only two values to 658 be considered: 660 1. The unix timestamp defined as unixts 662 2. The sub-second precision values defined as subsec_a, subsec_b, 663 and subsec_seq_node 665 As detailed in Figure 2 the unix timestamp (unixts) is always the 666 first 36 bits of the UUIDv7 layout. 668 Similarly as per Figure 2, the sub-second precision values lie within 669 subsec_a, subsec_b, and subsec_seq_node which are all interpreted as 670 sub-second information after skipping over the version (ver) and 671 (var) bits. These concatenated sub-second information bits are 672 interpreted in a way where most to least significant bits represent a 673 further division by two. This is the same normal place notation used 674 to express fractional numbers, except in binary. For example, in 675 decimal ".1" means one tenth, and ".01" means one hundredth. In this 676 subsec field, a 1 means one half, 01 means one quarter, 001 is one 677 eighth, etc. This scheme can work for any number of bits up to the 678 maximum available, and keeps the most significant data leftmost in 679 the bit sequence. 681 To perform the sub-second math, simply take the first (most 682 significant/leftmost) N bits of subsec and divide it by 2^N. Take 683 for example: 685 1. To parse the first 16 bits, extract that value as an integer and 686 divide it by 65536 (2 to the 16th). 688 2. If these 16 bits are 0101 0101 0101 0101, then treating that as 689 an integer gives 0x5555 or 21845 in decimal, and dividing by 690 65536 gives 0.3333282 692 This sub-second encoding scheme provides maximum interoperability 693 across systems where different levels of time precision are 694 required/feasible/available. The timestamp value derived from a 695 UUIDv7 value SHOULD be "as close to the correct value as possible" 696 when parsed, even across disparate systems. 698 Take for example the starting point for our next two UUIDv7 parsing 699 scenarios: 701 1. System A produces a UUIDv7 with a microsecond-precise timestamp 702 value. 704 2. System B is unaware of the precision encoded in the UUIDv7 705 timestamp by System A. 707 Scenario 1: 709 1. System B parses the embedded timestamp with millisecond 710 precision. (Less precision than the encoder) 712 2. System B SHOULD return the correct millisecond value encoded by 713 system A (truncated to milliseconds). 715 Scenario 2: 717 1. System B parses the timestamp with nanosecond precision. (More 718 precision than the encoder) 720 2. System B's value returned SHOULD have the same microsecond level 721 of precision provided by the encoder with the additional 722 precision down to nanosecond level being essentially random as 723 per the encoded random value at the end of the UUIDv7. 725 4.5. UUIDv8 Layout and Bit Order 727 UUIDv8 offers variable-size timestamp, clock sequence, and node 728 values which allow for a highly customizable UUID that fits a given 729 application needs. 731 UUIDv8 SHOULD only be utilized if an implementation cannot utilize 732 UUIDv1, UUIDv6, or UUIDv8. Some situations in which UUIDv8 usage 733 could occur: 735 * An implementation would like to utilize a timestamp source not 736 defined by the current time-based UUIDs. 738 * An implementation would like to utilize a timestamp bit layout not 739 defined by the current time-based UUIDs. 741 * An implementation would like a specific level of precision within 742 the timestamp not offered by current time-based UUIDs. 744 * An implementation would like to embed extra information within the 745 UUID node other than what is defined in this document. 747 * An implementation has other application/language restrictions 748 which inhibit the usage of one of the current time-based UUIDs. 750 Roughly speaking a properly formatted UUIDv8 SHOULD contain the 751 following sections adding up to a total of 128-bits. 753 - Timestamp Bits (Variable Length) 754 - Clock Sequence Bits (Variable Length) 755 - Node Bits (Variable Length) 756 - UUIDv8 Version Bits (4 bits) 757 - UUID Variant Bits (2 Bits) 759 The only explicitly defined bits are the Version and Variant leaving 760 122 bits for implementation specific time-based UUIDs. To be clear: 761 UUIDv8 is not a replacement for UUIDv4 where all 122 extra bits are 762 filled with random data. UUIDv8's 128 bits (including the version 763 and variant) SHOULD contain at the minimum a timestamp of some format 764 in the most significant bit position followed directly by a clock 765 sequence counter and finally a node containing either random data or 766 implementation specific data. 768 A sample format in Figure 6 is used to further illustrate the point 769 for the 16-octet, 128-bit UUIDv8. 771 0 1 2 3 772 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 773 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 774 | timestamp_32 | 775 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 776 | timestamp_48 | ver | time_or_seq | 777 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 778 |var| seq_or_node | node | 779 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 780 | node | 781 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 782 Figure 6: UUIDv8 Field and Bit Layout 784 timestamp_32: 785 The most significant 32 bits of the desired timestamp source. 786 Occupies bits 0 through 31 (octets 0-3). 788 timestamp_48: 789 The next 16-bits of the timestamp source when a timestamp source 790 with at least 48 bits is used. When a 32-bit timestamp source is 791 utilized, these bits are set to 0. Occupies bits 32 through 47 793 ver: 794 The 4 bit UUIDv8 version (1000). Occupies bits 48 through 51. 796 time_or_seq: 797 If a 60-bit, or larger, timestamp is used these 12-bits are used 798 to fill out the remaining timestamp. If a 32 or 48-bit timestamp 799 is leveraged a 12-bit clock sequence MAY be used. Together ver 800 and time_or_seq occupy bits 48 through 63 (octets 6-7) 802 var: 803 2-bit UUID variant (10) 805 seq_or_node: 806 If a 60-bit, or larger, timestamp source is leverages these 8 bits 807 SHOULD be allocated for an 8-bit clock sequence counter. If a 32 808 or 48 bit timestamp source is used these 8-bits SHOULD be set to 809 random. 811 node: 812 In most implementations these bits will likely be set to pseudo- 813 random data. However, implementations utilize the node as they 814 see fit. Together var, seq_or_node, and node occupy Bits 64 815 through 127 (octets 8-15) 817 4.5.1. UUIDv8 Timestamp Usage 819 UUIDv8's usage of timestamp relaxes both the timestamp source and 820 timestamp length. Implementations are free to utilize any 821 monotonically stable timestamp source for UUIDv8. 823 Some examples include: 825 - Custom Epoch 826 - NTP Timestamp 827 - ISO 8601 timestamp 829 The relaxed nature UUIDv8 timestamps also works to future proof this 830 specification and allow implementations a method to create compliant 831 time-based UUIDs using timestamp source that might not yet be 832 defined. 834 Timestamps come in many sizes and UUIDv8 defines three fields that 835 can easily used for the majority of timestamp lengths: 837 * 32-bit timestamp: using timestamp_32 and setting timestamp_48 to 838 0s 840 * 48-bit timestamp: using timestamp_32 and timestamp_48 entirely 842 * 60-bit timestamp: using timestamp_32, timestamp_48, and 843 time_or_seq 845 * 64-bit timestamp: using timestamp_32, timestamp_48, and 846 time_or_seq and truncating the timestamp the 60 most significant 847 bits. 849 Although it is possible to create a timestamp larger than 64-bits in 850 size The usage and bit layout of that timestamp format is up to the 851 implementation. When a timestamp exceeds the 64th bit (octet 7), 852 extra care must be taken to ensure the Variant bits are properly 853 inserted at their respective location in the UUID. Likewise, the 854 Version MUST always be implemented at the appropriate location. 856 Any timestamps that does not entirely fill the timestamp_32, 857 timestamp_48 or time_or_seq MUST set all leftover bits in the least 858 significant position of the respective field to 0. For example a 859 36-bit timestamp source would fully utilize timestamp_32 and 4-bits 860 of timestamp_48. The remaining 12-bits in timestamp_48 MUST be set 861 to 0. 863 By using implementation-specific timestamp sources it is not 864 guaranteed that devices outside of the application context are able 865 to extract and parse the timestamp from UUIDv8 without some pre- 866 existing knowledge of the source timestamp used by the UUIDv8 867 implementation. 869 4.5.2. UUIDv8 Clock Sequence Usage 871 A clock sequence MUST be used with UUIDv8 as added sequencing 872 guarantees when multiple UUIDv8 will be created on the same clock 873 tick. The amount of bits allocated to the clock sequence depends on 874 the precision of the timestamp source. For example, a more accurate 875 timestamp source using nanosecond precision will require less clock 876 sequence bits than a timestamp source utilizing seconds for 877 precision. 879 The UUIDv8 layout in Figure 6 generically defines two possible clock 880 sequence values that can leveraged: 882 * 12-bit clock sequence using time_or_seq for use when the timestamp 883 is less than 48-bits which allows for 4095 UUIDs per clock tick. 884 * 8-bit clock sequence using seq_or_node when the timestamp uses 885 more than 48-bits which allows for 255 UUIDs per clock tick. 887 An implementation MAY use both time_or_seq and seq_or_node for clock 888 sequencing however it is highly unlikely that 20-bits of clock 889 sequence are needed for a given clock tick. Furthermore, more bits 890 from the node MAY be used for clock sequencing in the event that 891 8-bits is not sufficient. 893 The clock sequence MUST start at zero and increment monotonically for 894 each new UUID created on by the application on the same timestamp. 895 When the timestamp increments the clock sequence MUST be reset to 896 zero. The clock sequence MUST NOT rollover or reset to zero unless 897 the timestamp has incremented. Care MUST be given to ensure that an 898 adequate sized clock sequence is selected for a given application 899 based on expected timestamp precision and expected UUID generation 900 rates. 902 4.5.3. UUIDv8 Node Usage 904 The UUIDv8 Node MAY contain any set of data an implementation desires 905 however the node MUST NOT be set to all 0s which does not ensure 906 global uniqueness. In most scenarios the node will be filled with 907 pseudo-random data. 909 The UUIDv8 layout in Figure 6 defines 2 sizes of Node depending on 910 the timestamp size: 912 * 62-bit node encompassing seq_or_node and node Used when a 913 timestamp of 48-bits or less is leveraged. 914 * 54-bit node when all 60-bits of the timestamp are in use and the 915 seq_or_node is used as clock sequencing. 917 An implementation MAY choose to allocate bits from the node to the 918 timestamp, clock sequence or application-specific embedded field. It 919 is recommended that implementation utilize a node of at least 48-bits 920 to ensure global uniqueness can be guaranteed. 922 4.5.4. UUIDv6 Basic Creation Algorithm 924 The entire usage of UUIDv8 is meant to be variable and allow as much 925 customization as possible to meet specific application/language 926 requirements. As such any UUIDv8 implementations will likely vary 927 among applications. 929 The following algorithm is a generic implementation using Figure 6 930 and the recommendations outlined in this specification. 932 *32-bit timestamp, 12-bit sequence counter, 62-bit node:* 934 1. From a system-wide shared stable store (e.g., a file) or global 935 variable, read the UUID generator state: the values of the 936 timestamp and clock sequence used to generate the last UUID. 938 2. Obtain the current time from the selected clock source as 32 939 bits. 941 3. Set the 32-bit field timestamp_32 to the 32 bits from the 942 timestamp 944 4. Set 16-bit timestamp_48 to all 0s 946 5. Set the version to 8 (1000) 948 6. If the state was unavailable (e.g., non-existent or corrupted) 949 or the timestamp is greater than the current timestamp; set the 950 12-bit clock sequence value (time_or_node) to 0 952 7. If the state was available, but the saved timestamp is less than 953 or equal to the current timestamp, increment the clock sequence 954 value (time_or_node). 956 8. Set the variant to binary 10 958 9. Generate 62 random bits and fill in 8-bits for seq_or_node and 959 54-bits for the node. 961 10. Format by concatenating the 128-bits as: timestamp_32|timestamp_ 962 48|version|time_or_node|variant|seq_or_node|node 964 11. Save the state (current timestamp and clock sequence) back to 965 the stable store 967 *48-bit timestamp, 12-bit sequence counter, 62-bit node:* 969 1. From a system-wide shared stable store (e.g., a file) or global 970 variable, read the UUID generator state: the values of the 971 timestamp and clock sequence used to generate the last UUID. 973 2. Obtain the current time from the selected clock source as 32 974 bits. 976 3. Set the 32-bit field timestamp_32 to the 32 most significant bits 977 from the timestamp 979 4. Set 16-bit timestamp_48 to the 16 least significant bits from the 980 timestamp 982 5. The rest of the steps are the same as the previous example. 984 *60-bit timestamp, 8-bit sequence counter, 54-bit node:* 986 1. From a system-wide shared stable store (e.g., a file) or global 987 variable, read the UUID generator state: the values of the 988 timestamp and clock sequence used to generate the last UUID. 990 2. Obtain the current time from the selected clock source as 32 991 bits. 993 3. Set the 32-bit field timestamp_32 to the 32 bits from the 994 timestamp 996 4. Set 16-bit timestamp_48 to the 16 middle bits from the timestamp 998 5. Set the version to 8 (1000) 1000 6. Set 12-bit time_or_node to the 12 least significant bits from 1001 the timestamp 1003 7. Set the variant to 10 1005 8. If the state was unavailable (e.g., non-existent or corrupted) 1006 or the timestamp is greater than the current timestamp; set the 1007 12-bit clock sequence value (seq_or_node) to 0 1009 9. If the state was available, but the saved timestamp is less than 1010 or equal to the current timestamp, increment the clock sequence 1011 value (seq_or_node). 1013 10. Generate 54 random bits and fill in the node 1015 11. Format by concatenating the 128-bits as: timestamp_32|timestamp_ 1016 48|version|time_or_node|variant|seq_or_node|node 1018 12. Save the state (current timestamp and clock sequence) back to 1019 the stable store 1021 *64-bit timestamp, 8-bit sequence counter, 54-bit node:* 1023 1. The same steps as the 60-bit timestamp can be utilized if the 1024 64-bit timestamp is truncated to 60-bits. 1026 2. Implementations MAY chose to truncate the most or least 1027 significant bits but it is recommended to utilize the most 1028 significant 60-bits and lose 4 bits of precision in the 1029 nanoseconds or microseconds position. 1031 *General algorithm for generation of UUIDv8 not defined here:* 1033 1. From a system-wide shared stable store (e.g., a file) or global 1034 variable, read the UUID generator state: the values of the 1035 timestamp and clock sequence used to generate the last UUID. 1037 2. Obtain the current time from the selected clock source as desired 1038 bit total 1040 3. Set total amount of bits for timestamp as required in the most 1041 significant positions of the 128-bit UUID 1043 4. Care MUST be taken to ensure that the UUID Version and UUID 1044 Variant are in the correct bit positions. 1046 UUID Version: Bits 48 through 51 1048 UUID Variant: Bits 64 and 65 1050 5. If the state was unavailable (e.g., non-existent or corrupted) or 1051 the timestamp is greater than the current timestamp; set the 1052 desired clock sequence value to 0 1054 6. If the state was available, but the saved timestamp is less than 1055 or equal to the current timestamp, increment the clock sequence 1056 value. 1058 7. Set the remaining bits to the node as pseudo-random data 1060 8. Format by concatenating the 128-bits together 1061 9. Save the state (current timestamp and clock sequence) back to the 1062 stable store 1064 5. Encoding and Storage 1066 The existing UUID hex and dash format of 8-4-4-4-12 is retained for 1067 both backwards compatibility and human readability. 1069 For many applications such as databases this format is unnecessarily 1070 verbose totaling 288 bits. 1072 * 8-bits for each of the 32 hex characters = 256 bits 1073 * 8-bits for each of the 4 hyphens = 32 bits 1075 Where possible UUIDs SHOULD be stored within database applications as 1076 the underlying 128-bit binary value. 1078 6. Global Uniqueness 1080 UUIDs created by this specification offer the same guarantees for 1081 global uniqueness as those found in [RFC4122]. Furthermore, the 1082 time-based UUIDs defined in this specification are geared towards 1083 database applications but MAY be used for a wide variety of use- 1084 cases. Just as global uniqueness is guaranteed, UUIDs are guaranteed 1085 to be unique within an application context within the enterprise 1086 domain. 1088 7. Distributed UUID Generation 1090 Some implementations might desire to utilize multi-node, clustered, 1091 applications which involve 2 or more applications independently 1092 generating UUIDs that will be stored in a common location. UUIDs 1093 already feature sufficient entropy to ensure that the chances of 1094 collision are low. However, implementations MAY dedicate a portion 1095 of the node's most significant random bits to a pseudo-random 1096 machineID which helps identify UUIDs created by a given node. This 1097 works to add an extra layer of collision avoidance. 1099 This machine ID MUST be placed in the UUID proceeding the timestamp 1100 and sequence counter bits. This position is selected to ensure that 1101 the sorting by timestamp and clock sequence is still possible. The 1102 machineID MUST NOT be an IEEE 802 MAC address. The creation and 1103 negotiation of the machineID among distributed nodes is out of scope 1104 for this specification. 1106 8. IANA Considerations 1108 This document has no IANA actions. 1110 9. Security Considerations 1112 MAC addresses pose inherent security risks and MUST not be used for 1113 node generation. As such they have been strictly forbidden from 1114 time-based UUIDs within this specification. Instead pseudo-random 1115 bits SHOULD selected from a source with sufficient entropy to ensure 1116 guaranteed uniqueness among UUID generation. 1118 Timestamps embedded in the UUID do pose a very small attack surface. 1119 The timestamp in conjunction with the clock sequence does signal the 1120 order of creation for a given UUID and it's corresponding data but 1121 does not define anything about the data itself or the application as 1122 a whole. If UUIDs are required for use with any security operation 1123 within an application context in any shape or form then [RFC4122] 1124 UUIDv4 SHOULD be utilized. 1126 The machineID portion of node, described in Section 7, does provide 1127 small unique identifier which could be used to determine which 1128 application is generating data but this machineID alone is not enough 1129 to identify a node on the network without other corresponding data 1130 points. Furthermore the machineID, like the timestamp+sequence, does 1131 not provide any context about the data the corresponds to the UUID or 1132 the current state of the application as a whole. 1134 10. Acknowledgements 1136 The authors gratefully acknowledge the contributions of Ben Campbell, 1137 Ben Ramsey, Fabio Lima, Gonzalo Salgueiro, Martin Thomson, Murray S. 1138 Kucherawy, Rick van Rein, Rob Wilton, Sean Leonard, Theodore Y. 1139 Ts'o. As well as all of those in and outside the IETF community to 1140 who contributed to the discussions which resulted in this document. 1142 11. Normative References 1144 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1145 Requirement Levels", BCP 14, RFC 2119, 1146 DOI 10.17487/RFC2119, March 1997, 1147 . 1149 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1150 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1151 DOI 10.17487/RFC4122, July 2005, 1152 . 1154 12. Informative References 1156 [LexicalUUID] 1157 Twitter, "A Scala client for Cassandra", commit f6da4e0, 1158 November 2012, 1159 . 1161 [Snowflake] 1162 Twitter, "Snowflake is a network service for generating 1163 unique ID numbers at high scale with some simple 1164 guarantees.", Commit b3f6a3c, May 2014, 1165 . 1168 [Flake] Boundary, "Flake: A decentralized, k-ordered id generation 1169 service in Erlang", Commit 15c933a, February 2017, 1170 . 1172 [ShardingID] 1173 Instagram Engineering, "Sharding & IDs at Instagram", 1174 December 2012, . 1177 [KSUID] Segment, "K-Sortable Globally Unique IDs", Commit bf376a7, 1178 July 2020, . 1180 [Elasticflake] 1181 Pearcy, P., "Sequential UUID / Flake ID generator pulled 1182 out of elasticsearch common", Commit dd71c21, January 1183 2015, . 1185 [FlakeID] Pawlak, T., "Flake ID Generator", Commit fcd6a2f, April 1186 2020, . 1188 [Sonyflake] 1189 Sony, "A distributed unique ID generator inspired by 1190 Twitter's Snowflake", Commit 848d664, August 2020, 1191 . 1193 [orderedUuid] 1194 Cabrera, IT., "Laravel: The mysterious "Ordered UUID"", 1195 January 2020, . 1198 [COMBGUID] Tallent, R., "Creating sequential GUIDs in C# for MSSQL or 1199 PostgreSql", Commit 2759820, December 2020, 1200 . 1202 [ULID] Feerasta, A., "Universally Unique Lexicographically 1203 Sortable Identifier", Commit d0c7170, May 2019, 1204 . 1206 [SID] Chilton, A., "sid : generate sortable identifiers", 1207 Commit 660e947, June 2019, 1208 . 1210 [pushID] Google, "The 2^120 Ways to Ensure Unique Identifiers", 1211 February 2015, . 1214 [XID] Poitrey, O., "Globally Unique ID Generator", 1215 Commit efa678f, October 2020, . 1217 [ObjectID] MongoDB, "ObjectId - MongoDB Manual", 1218 . 1221 [CUID] Elliott, E., "Collision-resistant ids optimized for 1222 horizontal scaling and performance.", Commit 215b27b, 1223 October 2020, . 1225 Authors' Addresses 1227 Brad G. Peabody 1229 Email: brad@peabody.io 1231 Kyzer R. Davis 1233 Email: kydavis@cisco.com