uuid5.nx source
↩ module page · 120 lines · 4159 B
1// uuid5.nx -- UUIDv5 (SHA-1 namespace + name -> UUID).
2//
3// RFC 4122 ยง4.3. Produces a DETERMINISTIC 128-bit UUID from a
4// namespace UUID + an arbitrary name. Same (ns, name) always
5// yields the same UUID. Used for:
6// - stable IDs derived from URLs (content hashing)
7// - deterministic object IDs in distributed systems
8// - test fixture IDs that don't drift between runs
9// - git-style content addressing without exposing the hash
10//
11// Algorithm:
12// hash = SHA-1(namespace_uuid_bytes || name_bytes)
13// uuid[0..16] = hash[0..16] (take first 16 bytes)
14// uuid[6] = (uuid[6] & 0x0F) | 0x50 (version = 5)
15// uuid[8] = (uuid[8] & 0x3F) | 0x80 (variant = RFC 4122)
16//
17// The RFC defines four standard namespace UUIDs for DNS, URL,
18// OID, and X.500 -- we expose them as byte constants. Callers
19// needing their own namespace mint a v4 UUID (uuid_v4_bytes)
20// once and reuse it forever.
21//
22// Invariants:
23// U5 1 Output is 16 bytes (not the hyphenated string; use
24// uuid_format from uuid.nx to get the string form).
25// U5 2 Deterministic: pure function of (ns, name).
26// U5 3 Byte-for-byte compatible with Python's uuid.uuid5,
27// Node's uuid library, java.util.UUID.nameUUIDFromBytes.
28
29import "syscalls.nx"
30import "nx_sha1.nx"
31
32// Standard namespaces (RFC 4122 Appendix C). All four are
33// 16 bytes; we expose them as function-returned pointers so
34// callers can just `memcpy` or pass them to uuid_v5.
35func uuid_ns_dns() -> *u8 {
36 // 6ba7b810-9dad-11d1-80b4-00c04fd430c8
37 return "\x6b\xa7\xb8\x10\x9d\xad\x11\xd1\x80\xb4\x00\xc0\x4f\xd4\x30\xc8"
38}
39func uuid_ns_url() -> *u8 {
40 // 6ba7b811-9dad-11d1-80b4-00c04fd430c8
41 return "\x6b\xa7\xb8\x11\x9d\xad\x11\xd1\x80\xb4\x00\xc0\x4f\xd4\x30\xc8"
42}
43func uuid_ns_oid() -> *u8 {
44 // 6ba7b812-9dad-11d1-80b4-00c04fd430c8
45 return "\x6b\xa7\xb8\x12\x9d\xad\x11\xd1\x80\xb4\x00\xc0\x4f\xd4\x30\xc8"
46}
47func uuid_ns_x500() -> *u8 {
48 // 6ba7b814-9dad-11d1-80b4-00c04fd430c8
49 return "\x6b\xa7\xb8\x14\x9d\xad\x11\xd1\x80\xb4\x00\xc0\x4f\xd4\x30\xc8"
50}
51
52// Produce a 16-byte UUIDv5. namespace must be 16 bytes; name
53// is an arbitrary byte sequence.
54func uuid_v5_bytes(namespace: *u8, name: *u8, name_len: i64,
55 out: *u8) -> i64 {
56 // Concatenate namespace || name into a scratch buffer.
57 let buf_len: i64 = 16 + name_len
58 let buf: *u8 = sys_mmap(buf_len + 16)
59 var i: i64 = 0
60 while i < 16 {
61 buf[i] = namespace[i]
62 i = i + 1
63 }
64 i = 0
65 while i < name_len {
66 buf[16 + i] = name[i]
67 i = i + 1
68 }
69
70 // SHA-1 -> 20 bytes; we keep first 16.
71 let hash: *u8 = sys_mmap(32)
72 sha1(buf, buf_len, hash)
73
74 i = 0
75 while i < 16 {
76 out[i] = hash[i]
77 i = i + 1
78 }
79
80 // Stamp version (5) and variant (RFC 4122 = 10xx).
81 out[6] = (out[6] & 0x0F) | 0x50
82 out[8] = (out[8] & 0x3F) | 0x80
83 return 0
84}
85
86// Compile-only smoke. RFC 4122 Appendix B worked example:
87// uuidv5(DNS, "python.org") = 886313e1-3b8a-5372-9b90-0c9aee199e5d
88func main() -> i64 {
89 let out: *u8 = sys_mmap(32)
90 uuid_v5_bytes(uuid_ns_dns(), "python.org", 10, out)
91
92 // Check first byte (0x88), version nibble, variant nibble.
93 if out[0] != 0x88 { return 1 }
94 if out[1] != 0x63 { return 2 }
95 // version nibble is high half of out[6].
96 if ((out[6] >> 4) & 0xF) != 5 { return 3 }
97 // variant is top two bits of out[8]: must be 10.
98 if ((out[8] >> 6) & 0x3) != 2 { return 4 }
99
100 // Determinism: same input -> same output.
101 let out2: *u8 = sys_mmap(32)
102 uuid_v5_bytes(uuid_ns_dns(), "python.org", 10, out2)
103 var i: i64 = 0
104 while i < 16 {
105 if out[i] != out2[i] { return 5 }
106 i = i + 1
107 }
108
109 // Different name -> different UUID.
110 let out3: *u8 = sys_mmap(32)
111 uuid_v5_bytes(uuid_ns_dns(), "ruby-lang.org", 13, out3)
112 var diff: i64 = 0
113 i = 0
114 while i < 16 {
115 if out[i] != out3[i] { diff = 1; break }
116 i = i + 1
117 }
118 if diff != 1 { return 6 }
119 return 0
120}