path: root/shared/ossp_uuid/uuid.pod

##
##  OSSP uuid - Universally Unique Identifier
##  Copyright (c) 2004-2008 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2004-2008 The OSSP Project <http://www.ossp.org/>
##
##  This file is part of OSSP uuid, a library for the generation
##  of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##
##  uuid.pod: manual page
##

=pod

=head1 NAME

B<OSSP uuid> - B<Universally Unique Identifier>

=head1 VERSION

OSSP uuid UUID_VERSION_STR

=head1 DESCRIPTION

B<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 I<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 B<OSSP uuid>.

=head2 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 C<0xF8
0x1D 0x4F 0xAE 0x7D 0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B
0xF6>. The binary representation format is exactly what the B<OSSP uuid>
API functions B<uuid_import>() and B<uuid_export>() deal with under
C<UUID_FMT_BIN>.

=head2 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
"C<f81d4fae-7dec-11d0-a765-00a0c91e6bf6>". The string representation
format is exactly what the B<OSSP uuid> API functions B<uuid_import>()
and B<uuid_export>() deal with under C<UUID_FMT_STR>.

Notice: a corresponding URL can be generated out of a ASCII string
representation of an UUID by prefixing with "C<urn:uuid:>" as in
"C<urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>".

=head2 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 "C<329800735698586629295641978511506172918>". The string
representation format is exactly what the B<OSSP uuid> API functions
B<uuid_import>() and B<uuid_export>() deal with under C<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 "C<2.25.>". An example OID
is "C<2.25.329800735698586629295641978511506172918>". Additionally,
an URL can be generated by further prefixing with "C<urn:oid:>" as in
"C<urn:oid:2.25.329800735698586629295641978511506172918>".

=head2 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 B<OSSP uuid> is the DCE 1.1 variant only. The DCE 1.1 UUID
variant versions supported in B<OSSP uuid> are:

=over 4

=item B<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.

=item B<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.

=item B<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.

=item B<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.

=back

=head2 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.

=head2 Nil UUID

There is a special I<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.

=head1 APPLICATION PROGRAMMING INTERFACE

The ISO-C Application Programming Interface (API) of B<OSSP uuid>
consists of the following components.

=head2 CONSTANTS

The following constants are provided:

=over 4

=item B<UUID_VERSION>

The hexadecimal encoded B<OSSP uuid> version. This allows compile-time
checking of the B<OSSP uuid> version. For run-time checking use
B<uuid_version>() instead.

The hexadecimal encoding for a version "$I<v>.$I<r>$I<t>$I<l>" is
calculated with the B<GNU shtool> B<version> command and is (in
Perl-style for concise description) "sprintf('0x%x%02x%d%02x', $I<v>,
$I<r>, {qw(s 9 . 2 b 1 a 0)}->{$I<t>}, ($I<t> eq 's' ? 99 : $I<l>))",
i.e., the version 0.9.6 is encoded as "0x009206".

=item B<UUID_LEN_BIN>, B<UUID_LEN_STR>, B<UUID_LEN_SIV>

The number of octets of the UUID binary and string representations.
Notice that the lengths of the string representation (B<UUID_LEN_STR>)
and the lengths of the single integer value representation
(B<UUID_LEN_SIV>) does I<not> include the necessary C<NUL> termination
character.

=item B<UUID_MAKE_V1>, B<UUID_MAKE_V3>, B<UUID_MAKE_V4>, B<UUID_MAKE_V5>, B<UUID_MAKE_MC>

The I<mode> bits for use with B<uuid_make>(). The B<UUID_MAKE_V>I<N>
specify which UUID version to generate. The B<UUID_MAKE_MC> forces the
use of a random multi-cast MAC address instead of the real physical MAC
address in version 1 UUIDs.

=item B<UUID_RC_OK>, B<UUID_RC_ARG>, B<UUID_RC_MEM>, B<UUID_RC_SYS>, B<UUID_RC_INT>, B<UUID_RC_IMP>

The possible numerical return-codes of API functions.
The C<UUID_RC_OK> indicates success, the others indicate errors.
Use B<uuid_error>() to translate them into string versions.

=item B<UUID_FMT_BIN>, B<UUID_FMT_STR>, B<UUID_FMT_SIV>, B<UUID_FMT_TXT>

The I<fmt> formats for use with B<uuid_import>() and B<uuid_export>().
The B<UUID_FMT_BIN> indicates the UUID binary representation (of
length B<UUID_LEN_BIN>), the B<UUID_FMT_STR> indicates the UUID string
representation (of length B<UUID_LEN_STR>), the B<UUID_FMT_SIV>
indicates the UUID single integer value representation (of maximum
length B<UUID_LEN_SIV>) and the B<UUID_FMT_TXT> indicates the textual
description (of arbitrary length) of a UUID.

=back

=head2 FUNCTIONS

The following functions are provided:

=over 4

=item uuid_rc_t B<uuid_create>(uuid_t **I<uuid>);

Create a new UUID object and store a pointer to it in C<*>I<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 I<Nil> UUID.

=item uuid_rc_t B<uuid_destroy>(uuid_t *I<uuid>);

Destroy UUID object I<uuid>.

=item uuid_rc_t B<uuid_clone>(const uuid_t *I<uuid>, uuid_t **I<uuid_clone>);

Clone UUID object I<uuid> and store new UUID object in I<uuid_clone>.

=item uuid_rc_t B<uuid_isnil>(const uuid_t *I<uuid>, int *I<result>);

Checks whether the UUID in I<uuid> is the I<Nil> UUID.
If this is the case, it returns I<true> in C<*>I<result>.
Else it returns I<false> in C<*>I<result>.

=item uuid_rc_t B<uuid_compare>(const uuid_t *I<uuid>, const uuid_t *I<uuid2>, int *I<result>);

Compares the order of the two UUIDs in I<uuid1> and I<uuid2>
and returns the result in C<*>I<result>: C<-1> if I<uuid1> is
smaller than I<uuid2>, C<0> if I<uuid1> is equal to I<uuid2>
and C<+1> if I<uuid1> is greater than I<uuid2>.

=item uuid_rc_t B<uuid_import>(uuid_t *I<uuid>, uuid_fmt_t I<fmt>, const void *I<data_ptr>, size_t I<data_len>);

Imports a UUID I<uuid> from an external representation of format I<fmt>.
The data is read from the buffer at I<data_ptr> which contains at least
I<data_len> bytes.

The format of the external representation is specified by I<fmt> and the
minimum expected length in I<data_len> depends on it. Valid values for
I<fmt> are B<UUID_FMT_BIN>, B<UUID_FMT_STR> and B<UUID_FMT_SIV>.

=item uuid_rc_t B<uuid_export>(const uuid_t *I<uuid>, uuid_fmt_t I<fmt>, void *I<data_ptr>, size_t *I<data_len>);

Exports a UUID I<uuid> into an external representation of format
I<fmt>. Valid values for I<fmt> are B<UUID_FMT_BIN>, B<UUID_FMT_STR>,
B<UUID_FMT_SIV> and B<UUID_FMT_TXT>.

The data is written to the buffer whose location is obtained
by dereferencing I<data_ptr> after a "cast" to the appropriate
pointer-to-pointer type. Hence the generic pointer argument I<data_ptr>
is expected to be a pointer to a "pointer of a particular type", i.e.,
it has to be of type "C<unsigned char **>" for B<UUID_FMT_BIN> and
"C<char **>" for B<UUID_FMT_STR>, B<UUID_FMT_SIV> and B<UUID_FMT_TXT>.

The buffer has to be room for at least C<*>I<data_len> bytes. If the
value of the pointer after "casting" and dereferencing I<data_ptr>
is C<NULL>, I<data_len> is ignored as input and a new buffer is
allocated and returned in the pointer after "casting" and dereferencing
I<data_ptr> (the caller has to free(3) it later on).

If I<data_len> is not C<NULL>, the number of available bytes in the
buffer has to be provided in C<*>I<data_len> and the number of actually
written bytes are returned in C<*>I<data_len> again. The minimum
required buffer length depends on the external representation as
specified by I<fmt> and is at least B<UUID_LEN_BIN> for B<UUID_FMT_BIN>,
B<UUID_LEN_STR> for B<UUID_FMT_STR> and B<UUID_LEN_SIV> for
B<UUID_FMT_SIV>. For B<UUID_FMT_TXT> a buffer of unspecified length is
required and hence it is recommended to allow B<OSSP uuid> to allocate
the buffer as necessary.

=item uuid_rc_t B<uuid_load>(uuid_t *I<uuid>, const char *I<name>);

Loads a pre-defined UUID value into the UUID object I<uuid>. The
following I<name> arguments are currently known:

=over 4

=item I<name>      I<UUID>

=item nil       00000000-0000-0000-0000-000000000000

=item ns:DNS    6ba7b810-9dad-11d1-80b4-00c04fd430c8

=item ns:URL    6ba7b811-9dad-11d1-80b4-00c04fd430c8

=item ns:OID    6ba7b812-9dad-11d1-80b4-00c04fd430c8

=item ns:X500   6ba7b814-9dad-11d1-80b4-00c04fd430c8

=back

The "C<ns:>I<XXX>" are names of pre-defined name-space UUIDs for use in
the generation of DCE 1.1 version 3 and version 5 UUIDs.

=item uuid_rc_t B<uuid_make>(uuid_t *I<uuid>, unsigned int I<mode>, ...);

Generates a new UUID in I<uuid> according to I<mode> and optional
arguments (dependent on I<mode>).

If I<mode> contains the C<UUID_MAKE_V1> bit, a DCE 1.1 variant UUID of
version 1 is generated. Then optionally the bit C<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 I<mode> contains the C<UUID_MAKE_V3> or C<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 (C<uuid_t *>).
Second, a name string of arbitrary length (C<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 I<mode> contains the C<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.

=item char *B<uuid_error>(uuid_rc_t I<rc>);

Returns a constant string representation corresponding to the
return-code I<rc> for use in displaying B<OSSP uuid> errors.

=item unsigned long B<uuid_version>(void);

Returns the hexadecimal encoded B<OSSP uuid> version as compiled into
the library object files. This allows run-time checking of the B<OSSP
uuid> version. For compile-time checking use C<UUID_VERSION> instead.

=back

=head1 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;
 }

=head1 SEE ALSO

The following are references to B<UUID> documentation and specifications:

=over 4

=item

B<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

=item

Information Technology -- Open Systems Interconnection (OSI),
B<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

=item

B<DCE 1.1: Remote Procedure Call>,
appendix B<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

=item

Information technology -- Open Systems Interconnection (OSI),
B<Remote Procedure Call (RPC)>,
ISO/IEC 11578:1996,
August 2001, 570 pages, (CHF 340,00),
http://www.iso.ch/cate/d2229.html

=item

B<HTTP Extensions for Distributed Authoring (WebDAV)>,
section B<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

=item

B<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

=back

=head1 HISTORY

B<OSSP uuid> was implemented in January 2004 by Ralf S. Engelschall
E<lt>rse@engelschall.comE<gt>. It was prompted by the use of UUIDs
in the B<OSSP as> and B<OpenPKG> projects. It is a clean room
implementation intended to be strictly standards compliant and maximum
portable.

=head1 SEE ALSO

uuid(1), uuid-config(1), OSSP::uuid(3).

=cut