Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
.::uuid(3)		 Universally Unique Identifier		    .::uuid(3)

NAME
       OSSP 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:

       o   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

       o   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

       o   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

       o   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

       o   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

       o   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).

04-Jul-2008			OSSP uuid 1.6.2			    .::uuid(3)

NAME | VERSION | DESCRIPTION | APPLICATION PROGRAMMING INTERFACE | EXAMPLE | SEE ALSO | HISTORY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ossp-uuid&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help