1.::uuid(3) Universally Unique Identifier .::uuid(3)
2
6 OSSP uuid - Universally Unique Identifier
7
9 OSSP uuid 1.5.1 (31-Jul-2006)
10
12 OSSP uuid is a ISO-C:1999 application programming interface (API) and
13 corresponding command line interface (CLI) for the generation of DCE
14 1.1, ISO/IEC 11578:1996 and RFC 4122 compliant Universally Unique Iden‐
15 tifier (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time and
16 node based), version 3 (name based, MD5), version 4 (random number
17 based) and version 5 (name based, SHA-1). Additional API bindings are
18 provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional
19 backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID
20 APIs.
21 UUIDs are 128 bit numbers which are intended to have a high likelihood
23 of uniqueness over space and time and are computationally difficult to
24 guess. They are globally unique identifiers which can be locally gener‐
25 ated without contacting a global registration authority. UUIDs are
26 intended as unique identifiers for both mass tagging objects with an
27 extremely short lifetime and to reliably identifying very persistent
28 objects across a network.
29 This is the ISO-C application programming interface (API) of OSSP uuid.
31 UUID Binary Representation
33 According to the DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 standards, a
35 DCE 1.1 variant UUID is a 128 bit number defined out of 7 fields, each
36 field a multiple of an octet in size and stored in network byte order:
37 [4]
39 version
40 -->⎪ ⎪<--
41 ⎪ ⎪
42 ⎪ ⎪ [16]
43 [32] [16] ⎪ ⎪time_hi
44 time_low time_mid ⎪ _and_version
45 ⎪<---------------------------->⎪⎪<------------>⎪⎪<------------>⎪
46 ⎪ MSB ⎪⎪ ⎪⎪ ⎪ ⎪
47 ⎪ / ⎪⎪ ⎪⎪ ⎪ ⎪
48 ⎪/ ⎪⎪ ⎪⎪ ⎪ ⎪
49 +------++------++------++------++------++------++------++------+~~
51 ⎪ 15 ⎪⎪ 14 ⎪⎪ 13 ⎪⎪ 12 ⎪⎪ 11 ⎪⎪ 10 ⎪####9 ⎪⎪ 8 ⎪
52 ⎪ MSO ⎪⎪ ⎪⎪ ⎪⎪ ⎪⎪ ⎪⎪ ⎪#### ⎪⎪ ⎪
53 +------++------++------++------++------++------++------++------+~~
54 7654321076543210765432107654321076543210765432107654321076543210
55 ~~+------++------++------++------++------++------++------++------+
57 ##* 7 ⎪⎪ 6 ⎪⎪ 5 ⎪⎪ 4 ⎪⎪ 3 ⎪⎪ 2 ⎪⎪ 1 ⎪⎪ 0 ⎪
58 ##* ⎪⎪ ⎪⎪ ⎪⎪ ⎪⎪ ⎪⎪ ⎪⎪ ⎪⎪ LSO ⎪
59 ~~+------++------++------++------++------++------++------++------+
60 7654321076543210765432107654321076543210765432107654321076543210
61 ⎪ ⎪ ⎪⎪ ⎪⎪ /⎪
63 ⎪ ⎪ ⎪⎪ ⎪⎪ / ⎪
64 ⎪ ⎪ ⎪⎪ ⎪⎪ LSB ⎪
65 ⎪<---->⎪⎪<---->⎪⎪<-------------------------------------------->⎪
66 ⎪clk_seq clk_seq node
67 ⎪_hi_res _low [48]
68 ⎪[5-6] [8]
69 ⎪ ⎪
70 -->⎪ ⎪<--
71 variant
72 [2-3]
73 An example of a UUID binary representation is the octet stream 0xF8
75 0x1D 0x4F 0xAE 0x7D 0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B
76 0xF6. The binary representation format is exactly what the OSSP uuid
77 API functions uuid_import() and uuid_export() deal with under
78 UUID_FMT_BIN.
79 UUID ASCII String Representation
81 According to the DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 standards, a
83 DCE 1.1 variant UUID is represented as an ASCII string consisting of 8
84 hexadecimal digits followed by a hyphen, then three groups of 4 hexa‐
85 decimal digits each followed by a hyphen, then 12 hexadecimal digits.
86 Formally, the string representation is defined by the following gram‐
87 mar:
88 uuid = <time_low> "-"
90 <time_mid> "-"
91 <time_high_and_version> "-"
92 <clock_seq_high_and_reserved>
93 <clock_seq_low> "-"
94 <node>
95 time_low = 4*<hex_octet>
96 time_mid = 2*<hex_octet>
97 time_high_and_version = 2*<hex_octet>
98 clock_seq_high_and_reserved = <hex_octet>
99 clock_seq_low = <hex_octet>
100 node = 6*<hex_octet>
101 hex_octet = <hex_digit> <hex_digit>
102 hex_digit = "0"⎪"1"⎪"2"⎪"3"⎪"4"⎪"5"⎪"6"⎪"7"⎪"8"⎪"9"
103 ⎪"a"⎪"b"⎪"c"⎪"d"⎪"e"⎪"f"
104 ⎪"A"⎪"B"⎪"C"⎪"D"⎪"E"⎪"F"
105 An example of a UUID string representation is the ASCII string
107 "f81d4fae-7dec-11d0-a765-00a0c91e6bf6". The string representation for‐
108 mat is exactly what the OSSP uuid API functions uuid_import() and
109 uuid_export() deal with under UUID_FMT_STR.
110 Notice: a corresponding URL can be generated out of a ASCII string rep‐
112 resentation of an UUID by prefixing with "urn:uuid:" as in
113 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6".
114 UUID Single Integer Value Representation
116 According to the ISO/IEC 11578:1996 and ITU-T Rec. X.667 standards, a
118 DCE 1.1 variant UUID can be also represented as a single integer value
119 consisting of a decimal number with up to 39 digits.
120 An example of a UUID single integer value representation is the decimal
122 number "329800735698586629295641978511506172918". The string represen‐
123 tation format is exactly what the OSSP uuid API functions uuid_import()
124 and uuid_export() deal with under UUID_FMT_SIV.
125 Notice: a corresponding ISO OID can be generated under the
127 "{joint-iso-itu-t(2) uuid(25)}" arc out of a single integer value rep‐
128 resentation of a UUID by prefixing with "2.25.". An example OID is
129 "2.25.329800735698586629295641978511506172918". Additionally, an URL
130 can be generated by further prefixing with "urn:oid:" as in
131 "urn:oid:2.25.329800735698586629295641978511506172918".
132 UUID Variants and Versions
134 A UUID has a variant and version. The variant defines the layout of the
136 UUID. The version defines the content of the UUID. The UUID variant
137 supported in OSSP uuid is the DCE 1.1 variant only. The DCE 1.1 UUID
138 variant versions supported in OSSP uuid are:
139 Version 1 (time and node based)
141 These are the classical UUIDs, created out of a 60-bit system time,
142 a 14-bit local clock sequence and 48-bit system MAC address. The
143 MAC address can be either the real one of a physical network inter‐
144 face card (NIC) or a random multi-cast MAC address. Version 1 UUIDs
145 are usually used as one-time global unique identifiers.
146 Version 3 (name based, MD5)
148 These are UUIDs which are based on the 128-bit MD5 message digest
149 of the concatenation of a 128-bit namespace UUID and a name string
150 of arbitrary length. Version 3 UUIDs are usually used for non-
151 unique but repeatable message digest identifiers.
152 Version 4 (random data based)
154 These are UUIDs which are based on just 128-bit of random data.
155 Version 4 UUIDs are usually used as one-time local unique identi‐
156 fiers.
157 Version 5 (name based, SHA-1)
159 These are UUIDs which are based on the 160-bit SHA-1 message digest
160 of the concatenation of a 128-bit namespace UUID and a name string
161 of arbitrary length. Version 5 UUIDs are usually used for non-
162 unique but repeatable message digest identifiers.
163 UUID Uniqueness
165 Version 1 UUIDs are guaranteed to be unique through combinations of
167 hardware addresses, time stamps and random seeds. There is a reference
168 in the UUID to the hardware (MAC) address of the first network inter‐
169 face card (NIC) on the host which generated the UUID -- this reference
170 is intended to ensure the UUID will be unique in space as the MAC
171 address of every network card is assigned by a single global authority
172 (IEEE) and is guaranteed to be unique. The next component in a UUID is
173 a timestamp which, as clock always (should) move forward, will be
174 unique in time. Just in case some part of the above goes wrong (the
175 hardware address cannot be determined or the clock moved steps back‐
176 ward), there is a random clock sequence component placed into the UUID
177 as a "catch-all" for uniqueness.
178 Version 3 and version 5 UUIDs are guaranteed to be inherently globally
180 unique if the combination of namespace and name used to generate them
181 is unique.
182 Version 4 UUIDs are not guaranteed to be globally unique, because they
184 are generated out of locally gathered pseudo-random numbers only. Nev‐
185 ertheless there is still a high likelihood of uniqueness over space and
186 time and that they are computationally difficult to guess.
187 Nil UUID
189 There is a special Nil UUID consisting of all octets set to zero in the
191 binary representation. It can be used as a special UUID value which
192 does not conflict with real UUIDs.
193
195 The ISO-C Application Programming Interface (API) of OSSP uuid consists
196 of the following components.
197 CONSTANTS
199 The following constants are provided:
201 UUID_VERSION
203 The hexadecimal encoded OSSP uuid version. This allows compile-time
204 checking of the OSSP uuid version. For run-time checking use
205 uuid_version() instead.
206 The hexadecimal encoding for a version "$v.$r$t$l" is calculated
208 with the GNU shtool version command and is (in Perl-style for con‐
209 cise description) "sprintf('0x%x%02x%d%02x', $v, $r, {qw(s 9 . 2 b
210 1 a 0)}->{$t}, ($t eq 's' ? 99 : $l))", i.e., the version 0.9.6 is
211 encoded as "0x009206".
212 UUID_LEN_BIN, UUID_LEN_STR, UUID_LEN_SIV
214 The number of octets of the UUID binary and string representations.
215 Notice that the lengths of the string representation (UUID_LEN_STR)
216 and the lengths of the single integer value representation
217 (UUID_LEN_SIV) does not include the necessary NUL termination char‐
218 acter.
219 UUID_MAKE_V1, UUID_MAKE_V3, UUID_MAKE_V4, UUID_MAKE_V5, UUID_MAKE_MC
221 The mode bits for use with uuid_make(). The UUID_MAKE_VN specify
222 which UUID version to generate. The UUID_MAKE_MC forces the use of
223 a random multi-cast MAC address instead of the real physical MAC
224 address in version 1 UUIDs.
225 UUID_RC_OK, UUID_RC_ARG, UUID_RC_MEM, UUID_RC_SYS, UUID_RC_INT,
227 UUID_RC_IMP
228 The possible numerical return-codes of API functions. The
229 UUID_RC_OK indicates success, the others indicate errors. Use
230 uuid_error() to translate them into string versions.
231 UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV, UUID_FMT_TXT
233 The fmt formats for use with uuid_import() and uuid_export(). The
234 UUID_FMT_BIN indicates the UUID binary representation (of length
235 UUID_LEN_BIN), the UUID_FMT_STR indicates the UUID string represen‐
236 tation (of length UUID_LEN_STR), the UUID_FMT_SIV indicates the
237 UUID single integer value representation (of maximum length
238 UUID_LEN_SIV) and the UUID_FMT_TXT indicates the textual descrip‐
239 tion (of arbitrary length) of a UUID.
240 FUNCTIONS
242 The following functions are provided:
244 uuid_rc_t uuid_create(uuid_t **uuid);
246 Create a new UUID object and store a pointer to it in *uuid. A
247 UUID object consists of an internal representation of a UUID, the
248 internal PRNG and MD5 generator contexts, and cached MAC address
249 and timestamp information. The initial UUID is the Nil UUID.
250 uuid_rc_t uuid_destroy(uuid_t *uuid);
252 Destroy UUID object uuid.
253 uuid_rc_t uuid_clone(const uuid_t *uuid, uuid_t **uuid_clone);
255 Clone UUID object uuid and store new UUID object in uuid_clone.
256 uuid_rc_t uuid_isnil(const uuid_t *uuid, int *result);
258 Checks whether the UUID in uuid is the Nil UUID. If this is the
259 case, it returns true in *result. Else it returns false in
260 *result.
261 uuid_rc_t uuid_compare(const uuid_t *uuid, const uuid_t *uuid2, int
263 *result);
264 Compares the order of the two UUIDs in uuid1 and uuid2 and returns
265 the result in *result: -1 if uuid1 is smaller than uuid2, 0 if
266 uuid1 is equal to uuid2 and +1 if uuid1 is greater than uuid2.
267 uuid_rc_t uuid_import(uuid_t *uuid, uuid_fmt_t fmt, const void
269 *data_ptr, size_t data_len);
270 Imports a UUID uuid from an external representation of format fmt.
271 The data is read from the buffer at data_ptr which contains at
272 least data_len bytes.
273 The format of the external representation is specified by fmt and
275 the minimum expected length in data_len depends on it. Valid values
276 for fmt are UUID_FMT_BIN, UUID_FMT_STR and UUID_FMT_SIV.
277 uuid_rc_t uuid_export(const uuid_t *uuid, uuid_fmt_t fmt, void
279 **data_ptr, size_t *data_len);
280 Exports a UUID uuid into an external representation of format fmt.
281 The data is written to the buffer at *data_ptr which has to be room
282 for at least *data_len bytes. If *data_ptr is NULL, data_len is
283 ignored as input and a new buffer is allocated and returned in
284 *data_ptr (the caller has to free(3) it later on). If data_len is
285 not NULL, the number of available bytes at *data_ptr has to be pro‐
286 vided in *data_len and the number of actually written bytes are
287 returned in *data_len again.
288 The format of the external representation is specified by fmt and
290 the minimum required length in *data_len depends on it. Valid val‐
291 ues for fmt are UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV and
292 UUID_FMT_TXT.
293 uuid_rc_t uuid_load(uuid_t *uuid, const char *name);
295 Loads a pre-defined UUID value into the UUID object uuid. The fol‐
296 lowing name arguments are currently known:
297 name UUID
299 nil 00000000-0000-0000-0000-000000000000
300 ns:DNS 6ba7b810-9dad-11d1-80b4-00c04fd430c8
301 ns:URL 6ba7b811-9dad-11d1-80b4-00c04fd430c8
302 ns:OID 6ba7b812-9dad-11d1-80b4-00c04fd430c8
303 ns:X500 6ba7b814-9dad-11d1-80b4-00c04fd430c8
304 The "ns:XXX" are names of pre-defined name-space UUIDs for use in
306 the generation of DCE 1.1 version 3 and version 5 UUIDs.
307 uuid_rc_t uuid_make(uuid_t *uuid, unsigned int mode, ...);
309 Generates a new UUID in uuid according to mode and optional argu‐
310 ments (dependent on mode).
311 If mode contains the UUID_MAKE_V1 bit, a DCE 1.1 variant UUID of
313 version 1 is generated. Then optionally the bit UUID_MAKE_MC forces
314 the use of random multi-cast MAC address instead of the real physi‐
315 cal MAC address (the default). The UUID is generated out of the
316 60-bit current system time, a 12-bit clock sequence and the 48-bit
317 MAC address.
318 If mode contains the UUID_MAKE_V3 or UUID_MAKE_V5 bit, a DCE 1.1
320 variant UUID of version 3 or 5 is generated and two additional
321 arguments are expected: first, a namespace UUID object (uuid_t *).
322 Second, a name string of arbitrary length (const char *). The UUID
323 is generated out of the 128-bit MD5 or 160-bit SHA-1 from the con‐
324 catenated octet stream of namespace UUID and name string.
325 If mode contains the UUID_MAKE_V4 bit, a DCE 1.1 variant UUID of
327 version 4 is generated. The UUID is generated out of 128-bit random
328 data.
329 char *uuid_error(uuid_rc_t rc);
331 Returns a constant string representation corresponding to the
332 return-code rc for use in displaying OSSP uuid errors.
333 unsigned long uuid_version(void);
335 Returns the hexadecimal encoded OSSP uuid version as compiled into
336 the library object files. This allows run-time checking of the OSSP
337 uuid version. For compile-time checking use UUID_VERSION instead.
338
340 The following shows an example usage of the API. Error handling is
341 omitted for code simplification and has to be re-added for production
342 code.
343 /* generate a DCE 1.1 v1 UUID from system environment */
345 char *uuid_v1(void)
346 {
347 uuid_t *uuid;
348 char *str;
349 uuid_create(&uuid);
351 uuid_make(uuid, UUID_MAKE_V1);
352 str = NULL;
353 uuid_export(uuid, UUID_FMT_STR, (void **)&str, NULL);
354 uuid_destroy(uuid);
355 return str;
356 }
357 /* generate a DCE 1.1 v3 UUID from an URL */
359 char *uuid_v3(const char *url)
360 {
361 uuid_t *uuid;
362 uuid_t *uuid_ns;
363 char *str;
364 uuid_create(&uuid);
366 uuid_create(&uuid_ns);
367 uuid_load(uuid_ns, "ns:URL");
368 uuid_make(uuid, UUID_MAKE_V3, uuid_ns, url);
369 str = NULL;
370 uuid_export(uuid, UUID_FMT_STR, (void **)&str, NULL);
371 uuid_destroy(uuid_ns);
372 uuid_destroy(uuid);
373 return str;
374 }
375
377 The following are references to UUID documentation and specifications:
378 · A Universally Unique IDentifier (UUID) URN Namespace, P. Leach, M.
380 Mealling, R. Salz, IETF RFC 4122, July 2005, 32 pages,
381 http://www.ietf.org/rfc/rfc4122.txt
382 · Information Technology -- Open Systems Interconnection (OSI), Pro‐
384 cedures for the operation of OSI Registration Authorities: Genera‐
385 tion and Registration of Universally Unique Identifiers (UUIDs) and
386 their Use as ASN.1 Object Identifier Components, ISO/IEC
387 9834-8:2004 / ITU-T Rec. X.667, 2004, December 2004, 25 pages,
388 http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf
389 · DCE 1.1: Remote Procedure Call, appendix Universally Unique Identi‐
391 fier, Open Group Technical Standard Document Number C706, August
392 1997, 737 pages, (supersedes C309 DCE: Remote Procedure Call
393 8/1994, which was basis for ISO/IEC 11578:1996 specification),
394 http://www.opengroup.org/publications/catalog/c706.htm
395 · Information technology -- Open Systems Interconnection (OSI),
397 Remote Procedure Call (RPC), ISO/IEC 11578:1996, August 2001, 570
398 pages, (CHF 340,00), http://www.iso.ch/cate/d2229.html
399 · HTTP Extensions for Distributed Authoring (WebDAV), section 6.4.1
401 Node Field Generation Without the IEEE 802 Address, IETF Request
402 for Comments: RFC 2518, February 1999, 94 pages,
403 http://www.ietf.org/rfc/rfc2518.txt
404 · DCE 1.1 compliant UUID functions, FreeBSD manual pages uuid(3) and
406 uuidgen(2), http://www.freebsd.org/cgi/man.cgi?query=uuid&man‐
407 path=FreeBSD+6.0-RELEASE
408
410 OSSP uuid was implemented in January 2004 by Ralf S. Engelschall
411 <rse@engelschall.com>. It was prompted by the use of UUIDs in the OSSP
412 as and OpenPKG projects. It is a clean room implementation intended to
413 be strictly standards compliant and maximum portable.
414
416 uuid(1), uuid-config(1), OSSP::uuid(3).
41731-Jul-2006 OSSP uuid 1.5.1 .::uuid(3)