diff options
Diffstat (limited to 'shared/ossp_uuid/uuid.pod')
| -rw-r--r-- | shared/ossp_uuid/uuid.pod | 529 |
1 files changed, 529 insertions, 0 deletions
diff --git a/shared/ossp_uuid/uuid.pod b/shared/ossp_uuid/uuid.pod new file mode 100644 index 00000000..4ad3742b --- /dev/null +++ b/shared/ossp_uuid/uuid.pod @@ -0,0 +1,529 @@ +## +## 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 + |