1.::uuid(3) Universally Unique Identifier .::uuid(3)
2
6 uuid - OSSP Universally Unique Identifier
7
9 OSSP uuid 1.6.2 (04-Jul-2008)
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 IETF RFC-4122 compliant Universally Unique
15 Identifier (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time
16 and 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
25 generated 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 IETF RFC-4122
35 standards, a DCE 1.1 variant UUID is a 128 bit number defined out of 7
36 fields, each field a multiple of an octet in size and stored in network
37 byte order:
38 [4]
40 version
41 -->| |<--
42 | |
43 | | [16]
44 [32] [16] | |time_hi
45 time_low time_mid | _and_version
46 |<---------------------------->||<------------>||<------------>|
47 | MSB || || | |
48 | / || || | |
49 |/ || || | |
50 +------++------++------++------++------++------++------++------+~~
52 | 15 || 14 || 13 || 12 || 11 || 10 |####9 || 8 |
53 | MSO || || || || || |#### || |
54 +------++------++------++------++------++------++------++------+~~
55 7654321076543210765432107654321076543210765432107654321076543210
56 ~~+------++------++------++------++------++------++------++------+
58 ##* 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0 |
59 ##* || || || || || || || LSO |
60 ~~+------++------++------++------++------++------++------++------+
61 7654321076543210765432107654321076543210765432107654321076543210
62 | | || || /|
64 | | || || / |
65 | | || || LSB |
66 |<---->||<---->||<-------------------------------------------->|
67 |clk_seq clk_seq node
68 |_hi_res _low [48]
69 |[5-6] [8]
70 | |
71 -->| |<--
72 variant
73 [2-3]
74 An example of a UUID binary representation is the octet stream 0xF8
76 0x1D 0x4F 0xAE 0x7D 0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B
77 0xF6. The binary representation format is exactly what the OSSP uuid
78 API functions uuid_import() and uuid_export() deal with under
79 UUID_FMT_BIN.
80 UUID ASCII String Representation
82 According to the DCE 1.1, ISO/IEC 11578:1996 and IETF RFC-4122
84 standards, a DCE 1.1 variant UUID is represented as an ASCII string
85 consisting of 8 hexadecimal digits followed by a hyphen, then three
86 groups of 4 hexadecimal digits each followed by a hyphen, then 12
87 hexadecimal digits. Formally, the string representation is defined by
88 the following grammar:
89 uuid = <time_low> "-"
91 <time_mid> "-"
92 <time_high_and_version> "-"
93 <clock_seq_high_and_reserved>
94 <clock_seq_low> "-"
95 <node>
96 time_low = 4*<hex_octet>
97 time_mid = 2*<hex_octet>
98 time_high_and_version = 2*<hex_octet>
99 clock_seq_high_and_reserved = <hex_octet>
100 clock_seq_low = <hex_octet>
101 node = 6*<hex_octet>
102 hex_octet = <hex_digit> <hex_digit>
103 hex_digit = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"
104 |"a"|"b"|"c"|"d"|"e"|"f"
105 |"A"|"B"|"C"|"D"|"E"|"F"
106 An example of a UUID string representation is the ASCII string
108 "f81d4fae-7dec-11d0-a765-00a0c91e6bf6". The string representation
109 format is exactly what the OSSP uuid API functions uuid_import() and
110 uuid_export() deal with under UUID_FMT_STR.
111 Notice: a corresponding URL can be generated out of a ASCII string
113 representation of an UUID by prefixing with "urn:uuid:" as in
114 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6".
115 UUID Single Integer Value Representation
117 According to the ISO/IEC 11578:1996 and ITU-T Rec. X.667 standards, a
119 DCE 1.1 variant UUID can be also represented as a single integer value
120 consisting of a decimal number with up to 39 digits.
121 An example of a UUID single integer value representation is the decimal
123 number "329800735698586629295641978511506172918". The string
124 representation format is exactly what the OSSP uuid API functions
125 uuid_import() and uuid_export() deal with under UUID_FMT_SIV.
126 Notice: a corresponding ISO OID can be generated under the
128 "{joint-iso-itu-t(2) uuid(25)}" arc out of a single integer value
129 representation of a UUID by prefixing with "2.25.". An example OID is
130 "2.25.329800735698586629295641978511506172918". Additionally, an URL
131 can be generated by further prefixing with "urn:oid:" as in
132 "urn:oid:2.25.329800735698586629295641978511506172918".
133 UUID Variants and Versions
135 A UUID has a variant and version. The variant defines the layout of the
137 UUID. The version defines the content of the UUID. The UUID variant
138 supported in OSSP uuid is the DCE 1.1 variant only. The DCE 1.1 UUID
139 variant versions supported in OSSP uuid are:
140 Version 1 (time and node based)
142 These are the classical UUIDs, created out of a 60-bit system time,
143 a 14-bit local clock sequence and 48-bit system MAC address. The
144 MAC address can be either the real one of a physical network
145 interface card (NIC) or a random multi-cast MAC address. Version 1
146 UUIDs are usually used as one-time global unique identifiers.
147 Version 3 (name based, MD5)
149 These are UUIDs which are based on the 128-bit MD5 message digest
150 of the concatenation of a 128-bit namespace UUID and a name string
151 of arbitrary length. Version 3 UUIDs are usually used for non-
152 unique but repeatable message digest identifiers.
153 Version 4 (random data based)
155 These are UUIDs which are based on just 128-bit of random data.
156 Version 4 UUIDs are usually used as one-time local unique
157 identifiers.
158 Version 5 (name based, SHA-1)
160 These are UUIDs which are based on the 160-bit SHA-1 message digest
161 of the concatenation of a 128-bit namespace UUID and a name string
162 of arbitrary length. Version 5 UUIDs are usually used for non-
163 unique but repeatable message digest identifiers.
164 UUID Uniqueness
166 Version 1 UUIDs are guaranteed to be unique through combinations of
168 hardware addresses, time stamps and random seeds. There is a reference
169 in the UUID to the hardware (MAC) address of the first network
170 interface card (NIC) on the host which generated the UUID -- this
171 reference is intended to ensure the UUID will be unique in space as the
172 MAC address of every network card is assigned by a single global
173 authority (IEEE) and is guaranteed to be unique. The next component in
174 a UUID is a timestamp which, as clock always (should) move forward,
175 will be unique in time. Just in case some part of the above goes wrong
176 (the hardware address cannot be determined or the clock moved steps
177 backward), there is a random clock sequence component placed into the
178 UUID as a "catch-all" for uniqueness.
179 Version 3 and version 5 UUIDs are guaranteed to be inherently globally
181 unique if the combination of namespace and name used to generate them
182 is unique.
183 Version 4 UUIDs are not guaranteed to be globally unique, because they
185 are generated out of locally gathered pseudo-random numbers only.
186 Nevertheless there is still a high likelihood of uniqueness over space
187 and time and that they are computationally difficult to guess.
188 Nil UUID
190 There is a special Nil UUID consisting of all octets set to zero in the
192 binary representation. It can be used as a special UUID value which
193 does not conflict with real UUIDs.
194
196 The ISO-C Application Programming Interface (API) of OSSP uuid consists
197 of the following components.
198 CONSTANTS
200 The following constants are provided:
202 UUID_VERSION
204 The hexadecimal encoded OSSP uuid version. This allows compile-time
205 checking of the OSSP uuid version. For run-time checking use
206 uuid_version() instead.
207 The hexadecimal encoding for a version "$v.$r$t$l" is calculated
209 with the GNU shtool version command and is (in Perl-style for
210 concise description) "sprintf('0x%x%02x%d%02x', $v, $r, {qw(s 9 . 2
211 b 1 a 0)}->{$t}, ($t eq 's' ? 99 : $l))", i.e., the version 0.9.6
212 is encoded as "0x009206".
213 UUID_LEN_BIN, UUID_LEN_STR, UUID_LEN_SIV
215 The number of octets of the UUID binary and string representations.
216 Notice that the lengths of the string representation (UUID_LEN_STR)
217 and the lengths of the single integer value representation
218 (UUID_LEN_SIV) does not include the necessary NUL termination
219 character.
220 UUID_MAKE_V1, UUID_MAKE_V3, UUID_MAKE_V4, UUID_MAKE_V5, UUID_MAKE_MC
222 The mode bits for use with uuid_make(). The UUID_MAKE_VN specify
223 which UUID version to generate. The UUID_MAKE_MC forces the use of
224 a random multi-cast MAC address instead of the real physical MAC
225 address in version 1 UUIDs.
226 UUID_RC_OK, UUID_RC_ARG, UUID_RC_MEM, UUID_RC_SYS, UUID_RC_INT,
228 UUID_RC_IMP
229 The possible numerical return-codes of API functions. The
230 UUID_RC_OK indicates success, the others indicate errors. Use
231 uuid_error() to translate them into string versions.
232 UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV, UUID_FMT_TXT
234 The fmt formats for use with uuid_import() and uuid_export(). The
235 UUID_FMT_BIN indicates the UUID binary representation (of length
236 UUID_LEN_BIN), the UUID_FMT_STR indicates the UUID string
237 representation (of length UUID_LEN_STR), the UUID_FMT_SIV indicates
238 the UUID single integer value representation (of maximum length
239 UUID_LEN_SIV) and the UUID_FMT_TXT indicates the textual
240 description (of arbitrary length) of a UUID.
241 FUNCTIONS
243 The following functions are provided:
245 uuid_rc_t uuid_create(uuid_t **uuid);
247 Create a new UUID object and store a pointer to it in *uuid. A
248 UUID object consists of an internal representation of a UUID, the
249 internal PRNG and MD5 generator contexts, and cached MAC address
250 and timestamp information. The initial UUID is the Nil UUID.
251 uuid_rc_t uuid_destroy(uuid_t *uuid);
253 Destroy UUID object uuid.
254 uuid_rc_t uuid_clone(const uuid_t *uuid, uuid_t **uuid_clone);
256 Clone UUID object uuid and store new UUID object in uuid_clone.
257 uuid_rc_t uuid_isnil(const uuid_t *uuid, int *result);
259 Checks whether the UUID in uuid is the Nil UUID. If this is the
260 case, it returns true in *result. Else it returns false in
261 *result.
262 uuid_rc_t uuid_compare(const uuid_t *uuid, const uuid_t *uuid2, int
264 *result);
265 Compares the order of the two UUIDs in uuid1 and uuid2 and returns
266 the result in *result: -1 if uuid1 is smaller than uuid2, 0 if
267 uuid1 is equal to uuid2 and +1 if uuid1 is greater than uuid2.
268 uuid_rc_t uuid_import(uuid_t *uuid, uuid_fmt_t fmt, const void
270 *data_ptr, size_t data_len);
271 Imports a UUID uuid from an external representation of format fmt.
272 The data is read from the buffer at data_ptr which contains at
273 least data_len bytes.
274 The format of the external representation is specified by fmt and
276 the minimum expected length in data_len depends on it. Valid values
277 for fmt are UUID_FMT_BIN, UUID_FMT_STR and UUID_FMT_SIV.
278 uuid_rc_t uuid_export(const uuid_t *uuid, uuid_fmt_t fmt, void
280 *data_ptr, size_t *data_len);
281 Exports a UUID uuid into an external representation of format fmt.
282 Valid values for fmt are UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV
283 and UUID_FMT_TXT.
284 The data is written to the buffer whose location is obtained by
286 dereferencing data_ptr after a "cast" to the appropriate pointer-
287 to-pointer type. Hence the generic pointer argument data_ptr is
288 expected to be a pointer to a "pointer of a particular type", i.e.,
289 it has to be of type "unsigned char **" for UUID_FMT_BIN and "char
290 **" for UUID_FMT_STR, UUID_FMT_SIV and UUID_FMT_TXT.
291 The buffer has to be room for at least *data_len bytes. If the
293 value of the pointer after "casting" and dereferencing data_ptr is
294 NULL, data_len is ignored as input and a new buffer is allocated
295 and returned in the pointer after "casting" and dereferencing
296 data_ptr (the caller has to free(3) it later on).
297 If data_len is not NULL, the number of available bytes in the
299 buffer has to be provided in *data_len and the number of actually
300 written bytes are returned in *data_len again. The minimum required
301 buffer length depends on the external representation as specified
302 by fmt and is at least UUID_LEN_BIN for UUID_FMT_BIN, UUID_LEN_STR
303 for UUID_FMT_STR and UUID_LEN_SIV for UUID_FMT_SIV. For
304 UUID_FMT_TXT a buffer of unspecified length is required and hence
305 it is recommended to allow OSSP uuid to allocate the buffer as
306 necessary.
307 uuid_rc_t uuid_load(uuid_t *uuid, const char *name);
309 Loads a pre-defined UUID value into the UUID object uuid. The
310 following name arguments are currently known:
311 name UUID
313 nil 00000000-0000-0000-0000-000000000000
314 ns:DNS 6ba7b810-9dad-11d1-80b4-00c04fd430c8
315 ns:URL 6ba7b811-9dad-11d1-80b4-00c04fd430c8
316 ns:OID 6ba7b812-9dad-11d1-80b4-00c04fd430c8
317 ns:X500 6ba7b814-9dad-11d1-80b4-00c04fd430c8
318 The "ns:XXX" are names of pre-defined name-space UUIDs for use in
320 the generation of DCE 1.1 version 3 and version 5 UUIDs.
321 uuid_rc_t uuid_make(uuid_t *uuid, unsigned int mode, ...);
323 Generates a new UUID in uuid according to mode and optional
324 arguments (dependent on mode).
325 If mode contains the UUID_MAKE_V1 bit, a DCE 1.1 variant UUID of
327 version 1 is generated. Then optionally the bit UUID_MAKE_MC forces
328 the use of random multi-cast MAC address instead of the real
329 physical MAC address (the default). The UUID is generated out of
330 the 60-bit current system time, a 12-bit clock sequence and the
331 48-bit MAC address.
332 If mode contains the UUID_MAKE_V3 or UUID_MAKE_V5 bit, a DCE 1.1
334 variant UUID of version 3 or 5 is generated and two additional
335 arguments are expected: first, a namespace UUID object (uuid_t *).
336 Second, a name string of arbitrary length (const char *). The UUID
337 is generated out of the 128-bit MD5 or 160-bit SHA-1 from the
338 concatenated octet stream of namespace UUID and name string.
339 If mode contains the UUID_MAKE_V4 bit, a DCE 1.1 variant UUID of
341 version 4 is generated. The UUID is generated out of 128-bit random
342 data.
343 char *uuid_error(uuid_rc_t rc);
345 Returns a constant string representation corresponding to the
346 return-code rc for use in displaying OSSP uuid errors.
347 unsigned long uuid_version(void);
349 Returns the hexadecimal encoded OSSP uuid version as compiled into
350 the library object files. This allows run-time checking of the OSSP
351 uuid version. For compile-time checking use UUID_VERSION instead.
352
354 The following shows an example usage of the API. Error handling is
355 omitted for code simplification and has to be re-added for production
356 code.
357 /* generate a DCE 1.1 v1 UUID from system environment */
359 char *uuid_v1(void)
360 {
361 uuid_t *uuid;
362 char *str;
363 uuid_create(&uuid);
365 uuid_make(uuid, UUID_MAKE_V1);
366 str = NULL;
367 uuid_export(uuid, UUID_FMT_STR, &str, NULL);
368 uuid_destroy(uuid);
369 return str;
370 }
371 /* generate a DCE 1.1 v3 UUID from an URL */
373 char *uuid_v3(const char *url)
374 {
375 uuid_t *uuid;
376 uuid_t *uuid_ns;
377 char *str;
378 uuid_create(&uuid);
380 uuid_create(&uuid_ns);
381 uuid_load(uuid_ns, "ns:URL");
382 uuid_make(uuid, UUID_MAKE_V3, uuid_ns, url);
383 str = NULL;
384 uuid_export(uuid, UUID_FMT_STR, &str, NULL);
385 uuid_destroy(uuid_ns);
386 uuid_destroy(uuid);
387 return str;
388 }
389
391 The following are references to UUID documentation and specifications:
392 · A Universally Unique IDentifier (UUID) URN Namespace, P. Leach, M.
394 Mealling, R. Salz, IETF RFC-4122, July 2005, 32 pages,
395 http://www.ietf.org/rfc/rfc4122.txt
396 · Information Technology -- Open Systems Interconnection (OSI),
398 Procedures for the operation of OSI Registration Authorities:
399 Generation and Registration of Universally Unique Identifiers
400 (UUIDs) and their Use as ASN.1 Object Identifier Components,
401 ISO/IEC 9834-8:2004 / ITU-T Rec. X.667, 2004, December 2004, 25
402 pages, http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf
403 · DCE 1.1: Remote Procedure Call, appendix Universally Unique
405 Identifier, Open Group Technical Standard Document Number C706,
406 August 1997, 737 pages, (supersedes C309 DCE: Remote Procedure Call
407 8/1994, which was basis for ISO/IEC 11578:1996 specification),
408 http://www.opengroup.org/publications/catalog/c706.htm
409 · Information technology -- Open Systems Interconnection (OSI),
411 Remote Procedure Call (RPC), ISO/IEC 11578:1996, August 2001, 570
412 pages, (CHF 340,00), http://www.iso.ch/cate/d2229.html
413 · HTTP Extensions for Distributed Authoring (WebDAV), section 6.4.1
415 Node Field Generation Without the IEEE 802 Address, IETF RFC-2518,
416 February 1999, 94 pages, http://www.ietf.org/rfc/rfc2518.txt
417 · DCE 1.1 compliant UUID functions, FreeBSD manual pages uuid(3) and
419 uuidgen(2),
420 http://www.freebsd.org/cgi/man.cgi?query=uuid&manpath=FreeBSD+6.0-RELEASE
421
423 OSSP uuid was implemented in January 2004 by Ralf S. Engelschall
424 <rse@engelschall.com>. It was prompted by the use of UUIDs in the OSSP
425 as and OpenPKG projects. It is a clean room implementation intended to
426 be strictly standards compliant and maximum portable.
427
429 uuid(1), uuid-config(1), OSSP::uuid(3).
43004-Jul-2008 OSSP uuid 1.6.2 .::uuid(3)