NAME¶
uuid - Universally Unique Identifier
VERSION¶
OSSP uuid 1.6.2 (04-Jul-2008)
DESCRIPTION¶
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.
UUID Binary Representation¶
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.
UUID ASCII String Representation¶
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".
UUID Single Integer Value Representation¶
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".
UUID Variants and Versions¶
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 (time and node based)
- These are the classical UUIDs, created out of a 60-bit
system time, a 14-bit local clock sequence and 48-bit system MAC address.
The MAC address can be either the real one of a physical network interface
card (NIC) or a random multi-cast MAC address. Version 1 UUIDs are usually
used as one-time global unique identifiers.
- Version 3 (name based, MD5)
- These are UUIDs which are based on the 128-bit MD5 message
digest of the concatenation of a 128-bit namespace UUID and a name string
of arbitrary length. Version 3 UUIDs are usually used for non-unique but
repeatable message digest identifiers.
- Version 4 (random data based)
- These are UUIDs which are based on just 128-bit of random
data. Version 4 UUIDs are usually used as one-time local unique
identifiers.
- Version 5 (name based, SHA-1)
- These are UUIDs which are based on the 160-bit SHA-1
message digest of the concatenation of a 128-bit namespace UUID and a name
string of arbitrary length. Version 5 UUIDs are usually used for
non-unique but repeatable message digest identifiers.
UUID Uniqueness¶
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.
Nil UUID¶
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.
APPLICATION PROGRAMMING INTERFACE¶
The ISO-C Application Programming Interface (API) of
OSSP uuid consists
of the following components.
CONSTANTS¶
The following constants are provided:
- UUID_VERSION
- The hexadecimal encoded OSSP uuid version. This
allows compile-time checking of the OSSP uuid version. For run-time
checking use uuid_version() instead.
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".
- UUID_LEN_BIN, UUID_LEN_STR,
UUID_LEN_SIV
- The number of octets of the UUID binary and string
representations. Notice that the lengths of the string representation (
UUID_LEN_STR) and the lengths of the single integer value
representation ( UUID_LEN_SIV) does not include the
necessary NUL termination character.
- UUID_MAKE_V1, UUID_MAKE_V3,
UUID_MAKE_V4, UUID_MAKE_V5, UUID_MAKE_MC
- The mode bits for use with uuid_make(). The
UUID_MAKE_VN specify which UUID version to generate. The
UUID_MAKE_MC forces the use of a random multi-cast MAC address
instead of the real physical MAC address in version 1 UUIDs.
- UUID_RC_OK, UUID_RC_ARG, UUID_RC_MEM,
UUID_RC_SYS, UUID_RC_INT, UUID_RC_IMP
- The possible numerical return-codes of API functions. The
UUID_RC_OK indicates success, the others indicate errors. Use
uuid_error() to translate them into string versions.
- UUID_FMT_BIN, UUID_FMT_STR,
UUID_FMT_SIV, UUID_FMT_TXT
- The fmt formats for use with uuid_import()
and uuid_export(). The UUID_FMT_BIN indicates the UUID
binary representation (of length UUID_LEN_BIN), the
UUID_FMT_STR indicates the UUID string representation (of length
UUID_LEN_STR), the UUID_FMT_SIV indicates the UUID single
integer value representation (of maximum length UUID_LEN_SIV) and
the UUID_FMT_TXT indicates the textual description (of arbitrary
length) of a UUID.
FUNCTIONS¶
The following functions are provided:
- uuid_rc_t uuid_create(uuid_t **uuid);
- Create a new UUID object and store a pointer to it in
*uuid. A UUID object consists of an internal representation of a
UUID, the internal PRNG and MD5 generator contexts, and cached MAC address
and timestamp information. The initial UUID is the Nil UUID.
- uuid_rc_t uuid_destroy(uuid_t *uuid);
- Destroy UUID object uuid.
- uuid_rc_t uuid_clone(const uuid_t *uuid,
uuid_t ** uuid_clone);
- Clone UUID object uuid and store new UUID object in
uuid_clone.
- uuid_rc_t uuid_isnil(const uuid_t *uuid, int
* result);
- Checks whether the UUID in uuid is the Nil
UUID. If this is the case, it returns true in *result. Else
it returns false in *result.
- uuid_rc_t uuid_compare(const uuid_t *uuid,
const uuid_t * uuid2, int *result);
- Compares the order of the two UUIDs in uuid1 and
uuid2 and returns the result in * result: -1 if uuid1
is smaller than uuid2, 0 if uuid1 is equal to uuid2
and +1 if uuid1 is greater than uuid2.
- uuid_rc_t uuid_import(uuid_t *uuid,
uuid_fmt_t fmt, const void *data_ptr, size_t
data_len);
- Imports a UUID uuid from an external representation
of format fmt. The data is read from the buffer at data_ptr
which contains at least data_len bytes.
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.
- uuid_rc_t uuid_export(const uuid_t *uuid,
uuid_fmt_t fmt, void *data_ptr, size_t *data_len);
- Exports a UUID uuid into an external representation
of format fmt. Valid values for fmt are UUID_FMT_BIN,
UUID_FMT_STR, UUID_FMT_SIV and UUID_FMT_TXT.
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.
- uuid_rc_t uuid_load(uuid_t *uuid, const char
* name);
- Loads a pre-defined UUID value into the UUID object
uuid. The following name arguments are currently known:
- name UUID
- nil 00000000-0000-0000-0000-000000000000
- ns:DNS 6ba7b810-9dad-11d1-80b4-00c04fd430c8
- ns:URL 6ba7b811-9dad-11d1-80b4-00c04fd430c8
- ns:OID 6ba7b812-9dad-11d1-80b4-00c04fd430c8
- ns:X500 6ba7b814-9dad-11d1-80b4-00c04fd430c8
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.
- uuid_rc_t uuid_make(uuid_t *uuid, unsigned
int mode, ...);
- Generates a new UUID in uuid according to
mode and optional arguments (dependent on mode).
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.
- char *uuid_error(uuid_rc_t rc);
- Returns a constant string representation corresponding to
the return-code rc for use in displaying OSSP uuid
errors.
- unsigned long uuid_version(void);
- Returns the hexadecimal encoded OSSP uuid version as
compiled into the library object files. This allows run-time checking of
the OSSP uuid version. For compile-time checking use
UUID_VERSION instead.
EXAMPLE¶
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;
}
SEE ALSO¶
The following are references to
UUID documentation and specifications:
- •
- A Universally Unique IDentifier (UUID) URN
Namespace, P. Leach, M. Mealling, R. Salz, IETF RFC-4122, July 2005,
32 pages, http://www.ietf.org/rfc/rfc4122.txt
- •
- Information Technology -- Open Systems Interconnection
(OSI), Procedures for the operation of OSI Registration
Authorities: Generation and Registration of Universally Unique
Identifiers (UUIDs) and their Use as ASN.1 Object Identifier
Components, ISO/IEC 9834-8:2004 / ITU-T Rec. X.667, 2004, December
2004, 25 pages,
http://www.itu.int/ITU-T/studygroups/com17/oid/X.667-E.pdf
- •
- DCE 1.1: Remote Procedure Call, appendix
Universally Unique Identifier, Open Group Technical Standard
Document Number C706, August 1997, 737 pages, (supersedes C309 DCE: Remote
Procedure Call 8/1994, which was basis for ISO/IEC 11578:1996
specification),
http://www.opengroup.org/publications/catalog/c706.htm
- •
- Information technology -- Open Systems Interconnection
(OSI), Remote Procedure Call (RPC), ISO/IEC 11578:1996, August
2001, 570 pages, (CHF 340,00), http://www.iso.ch/cate/d2229.html
- •
- HTTP Extensions for Distributed Authoring (WebDAV),
section 6.4.1 Node Field Generation Without the IEEE 802 Address,
IETF RFC-2518, February 1999, 94 pages,
http://www.ietf.org/rfc/rfc2518.txt
- •
- DCE 1.1 compliant UUID functions, FreeBSD manual
pages uuid(3) and uuidgen(2),
http://www.freebsd.org/cgi/man.cgi?query=uuid&manpath=FreeBSD+6.0-RELEASE
HISTORY¶
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.
SEE ALSO¶
uuid(1),
uuid-config(1), OSSP::
uuid(3).