.::uuid(3) | Universally Unique Identifier | .::uuid(3) |
uuid - Universally Unique Identifier
OSSP uuid 1.6.2 (04-Jul-2008)
OSSP uuid is a ISO-C:1999 application programming interface (API) and corresponding command line interface (CLI) for the generation of DCE 1.1, ISO/IEC 11578:1996 and IETF RFC-4122 compliant Universally Unique Identifier (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time and node based), version 3 (name based, MD5), version 4 (random number based) and version 5 (name based, SHA-1). Additional API bindings are provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID APIs.
UUIDs are 128 bit numbers which are intended to have a high likelihood of uniqueness over space and time and are computationally difficult to guess. They are globally unique identifiers which can be locally generated without contacting a global registration authority. UUIDs are intended as unique identifiers for both mass tagging objects with an extremely short lifetime and to reliably identifying very persistent objects across a network.
This is the ISO-C application programming interface (API) of OSSP uuid.
According to the DCE 1.1, ISO/IEC 11578:1996 and IETF RFC-4122 standards, a DCE 1.1 variant UUID is a 128 bit number defined out of 7 fields, each field a multiple of an octet in size and stored in network byte order:
[4] version -->| |<-- | | | | [16] [32] [16] | |time_hi time_low time_mid | _and_version |<---------------------------->||<------------>||<------------>| | MSB || || | | | / || || | | |/ || || | | +------++------++------++------++------++------++------++------+~~ | 15 || 14 || 13 || 12 || 11 || 10 |####9 || 8 | | MSO || || || || || |#### || | +------++------++------++------++------++------++------++------+~~ 7654321076543210765432107654321076543210765432107654321076543210 ~~+------++------++------++------++------++------++------++------+ ##* 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0 | ##* || || || || || || || LSO | ~~+------++------++------++------++------++------++------++------+ 7654321076543210765432107654321076543210765432107654321076543210 | | || || /| | | || || / | | | || || LSB | |<---->||<---->||<-------------------------------------------->| |clk_seq clk_seq node |_hi_res _low [48] |[5-6] [8] | | -->| |<-- variant [2-3]
An example of a UUID binary representation is the octet stream 0xF8 0x1D 0x4F 0xAE 0x7D 0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B 0xF6. The binary representation format is exactly what the OSSP uuid API functions uuid_import() and uuid_export() deal with under UUID_FMT_BIN.
According to the DCE 1.1, ISO/IEC 11578:1996 and IETF RFC-4122 standards, a DCE 1.1 variant UUID is represented as an ASCII string consisting of 8 hexadecimal digits followed by a hyphen, then three groups of 4 hexadecimal digits each followed by a hyphen, then 12 hexadecimal digits. Formally, the string representation is defined by the following grammar:
uuid = <time_low> "-" <time_mid> "-" <time_high_and_version> "-" <clock_seq_high_and_reserved> <clock_seq_low> "-" <node> time_low = 4*<hex_octet> time_mid = 2*<hex_octet> time_high_and_version = 2*<hex_octet> clock_seq_high_and_reserved = <hex_octet> clock_seq_low = <hex_octet> node = 6*<hex_octet> hex_octet = <hex_digit> <hex_digit> hex_digit = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9" |"a"|"b"|"c"|"d"|"e"|"f" |"A"|"B"|"C"|"D"|"E"|"F"
An example of a UUID string representation is the ASCII string "f81d4fae-7dec-11d0-a765-00a0c91e6bf6". The string representation format is exactly what the OSSP uuid API functions uuid_import() and uuid_export() deal with under UUID_FMT_STR.
Notice: a corresponding URL can be generated out of a ASCII string representation of an UUID by prefixing with "urn:uuid:" as in "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6".
According to the ISO/IEC 11578:1996 and ITU-T Rec. X.667 standards, a DCE 1.1 variant UUID can be also represented as a single integer value consisting of a decimal number with up to 39 digits.
An example of a UUID single integer value representation is the decimal number "329800735698586629295641978511506172918". The string representation format is exactly what the OSSP uuid API functions uuid_import() and uuid_export() deal with under UUID_FMT_SIV.
Notice: a corresponding ISO OID can be generated under the "{joint-iso-itu-t(2) uuid(25)}" arc out of a single integer value representation of a UUID by prefixing with "2.25.". An example OID is "2.25.329800735698586629295641978511506172918". Additionally, an URL can be generated by further prefixing with "urn:oid:" as in "urn:oid:2.25.329800735698586629295641978511506172918".
A UUID has a variant and version. The variant defines the layout of the UUID. The version defines the content of the UUID. The UUID variant supported in OSSP uuid is the DCE 1.1 variant only. The DCE 1.1 UUID variant versions supported in OSSP uuid are:
Version 1 UUIDs are guaranteed to be unique through combinations of hardware addresses, time stamps and random seeds. There is a reference in the UUID to the hardware (MAC) address of the first network interface card (NIC) on the host which generated the UUID -- this reference is intended to ensure the UUID will be unique in space as the MAC address of every network card is assigned by a single global authority (IEEE) and is guaranteed to be unique. The next component in a UUID is a timestamp which, as clock always (should) move forward, will be unique in time. Just in case some part of the above goes wrong (the hardware address cannot be determined or the clock moved steps backward), there is a random clock sequence component placed into the UUID as a "catch-all" for uniqueness.
Version 3 and version 5 UUIDs are guaranteed to be inherently globally unique if the combination of namespace and name used to generate them is unique.
Version 4 UUIDs are not guaranteed to be globally unique, because they are generated out of locally gathered pseudo-random numbers only. Nevertheless there is still a high likelihood of uniqueness over space and time and that they are computationally difficult to guess.
There is a special Nil UUID consisting of all octets set to zero in the binary representation. It can be used as a special UUID value which does not conflict with real UUIDs.
The ISO-C Application Programming Interface (API) of OSSP uuid consists of the following components.
The following constants are provided:
The hexadecimal encoding for a version "$v.$r$t$l" is calculated with the GNU shtool version command and is (in Perl-style for concise description) "sprintf('0x%x%02x%d%02x', $v, $r, {qw(s 9 . 2 b 1 a 0)}->{$t}, ($t eq 's' ? 99 : $l))", i.e., the version 0.9.6 is encoded as "0x009206".
The following functions are provided:
The format of the external representation is specified by fmt and the minimum expected length in data_len depends on it. Valid values for fmt are UUID_FMT_BIN, UUID_FMT_STR and UUID_FMT_SIV.
The data is written to the buffer whose location is obtained by dereferencing data_ptr after a "cast" to the appropriate pointer-to-pointer type. Hence the generic pointer argument data_ptr is expected to be a pointer to a "pointer of a particular type", i.e., it has to be of type "unsigned char **" for UUID_FMT_BIN and "char **" for UUID_FMT_STR, UUID_FMT_SIV and UUID_FMT_TXT.
The buffer has to be room for at least *data_len bytes. If the value of the pointer after "casting" and dereferencing data_ptr is NULL, data_len is ignored as input and a new buffer is allocated and returned in the pointer after "casting" and dereferencing data_ptr (the caller has to free(3) it later on).
If data_len is not NULL, the number of available bytes in the buffer has to be provided in *data_len and the number of actually written bytes are returned in *data_len again. The minimum required buffer length depends on the external representation as specified by fmt and is at least UUID_LEN_BIN for UUID_FMT_BIN, UUID_LEN_STR for UUID_FMT_STR and UUID_LEN_SIV for UUID_FMT_SIV. For UUID_FMT_TXT a buffer of unspecified length is required and hence it is recommended to allow OSSP uuid to allocate the buffer as necessary.
The "ns:XXX" are names of pre-defined name-space UUIDs for use in the generation of DCE 1.1 version 3 and version 5 UUIDs.
If mode contains the UUID_MAKE_V1 bit, a DCE 1.1 variant UUID of version 1 is generated. Then optionally the bit UUID_MAKE_MC forces the use of random multi-cast MAC address instead of the real physical MAC address (the default). The UUID is generated out of the 60-bit current system time, a 12-bit clock sequence and the 48-bit MAC address.
If mode contains the UUID_MAKE_V3 or UUID_MAKE_V5 bit, a DCE 1.1 variant UUID of version 3 or 5 is generated and two additional arguments are expected: first, a namespace UUID object (uuid_t *). Second, a name string of arbitrary length (const char *). The UUID is generated out of the 128-bit MD5 or 160-bit SHA-1 from the concatenated octet stream of namespace UUID and name string.
If mode contains the UUID_MAKE_V4 bit, a DCE 1.1 variant UUID of version 4 is generated. The UUID is generated out of 128-bit random data.
The following shows an example usage of the API. Error handling is omitted for code simplification and has to be re-added for production code.
/* generate a DCE 1.1 v1 UUID from system environment */ char *uuid_v1(void) { uuid_t *uuid; char *str; uuid_create(&uuid); uuid_make(uuid, UUID_MAKE_V1); str = NULL; uuid_export(uuid, UUID_FMT_STR, &str, NULL); uuid_destroy(uuid); return str; } /* generate a DCE 1.1 v3 UUID from an URL */ char *uuid_v3(const char *url) { uuid_t *uuid; uuid_t *uuid_ns; char *str; uuid_create(&uuid); uuid_create(&uuid_ns); uuid_load(uuid_ns, "ns:URL"); uuid_make(uuid, UUID_MAKE_V3, uuid_ns, url); str = NULL; uuid_export(uuid, UUID_FMT_STR, &str, NULL); uuid_destroy(uuid_ns); uuid_destroy(uuid); return str; }
The following are references to UUID documentation and specifications:
OSSP uuid was implemented in January 2004 by Ralf S. Engelschall <rse@engelschall.com>. It was prompted by the use of UUIDs in the OSSP as and OpenPKG projects. It is a clean room implementation intended to be strictly standards compliant and maximum portable.
OSSP uuid 1.6.2 | 04-Jul-2008 |