164 lines
4.6 KiB
Plaintext
164 lines
4.6 KiB
Plaintext
|
|
||
|
<sect1 id="uuid-ossp">
|
||
|
<title>uuid-ossp</title>
|
||
|
|
||
|
<indexterm zone="uuid-ossp">
|
||
|
<primary>uuid-ossp</primary>
|
||
|
</indexterm>
|
||
|
|
||
|
<para>
|
||
|
This module provides functions to generate universally unique
|
||
|
identifiers (UUIDs) using one of the several standard algorithms, as
|
||
|
well as functions to produce certain special UUID constants.
|
||
|
</para>
|
||
|
|
||
|
<sect2>
|
||
|
<title>UUID Generation</title>
|
||
|
<para>
|
||
|
The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and RFC
|
||
|
4122 specify four algorithms for generating UUIDs, identified by the
|
||
|
version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.)
|
||
|
Each of these algorithms could be suitable for a different set of
|
||
|
applications.
|
||
|
</para>
|
||
|
|
||
|
<table>
|
||
|
<title><literal>uuid-ossp</literal> functions</title>
|
||
|
<tgroup cols="2">
|
||
|
<thead>
|
||
|
<row>
|
||
|
<entry>Function</entry>
|
||
|
<entry>Description</entry>
|
||
|
</row>
|
||
|
</thead>
|
||
|
<tbody>
|
||
|
<row>
|
||
|
<entry><literal>uuid_generate_v1()</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
This function generates a version 1 UUID. This involves the MAC
|
||
|
address of the computer and a time stamp. Note that UUIDs of this
|
||
|
kind reveal the identity of the computer that created the identifier
|
||
|
and the time at which it did so, which might make it unsuitable for
|
||
|
certain security-sensitive applications.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_generate_v1mc()</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
This function generates a version 1 UUID but uses a random multicast
|
||
|
MAC address instead of the real MAC address of the computer.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_generate_v3(namespace uuid, name text)</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
This function generates a version 3 UUID in the given namespace using
|
||
|
the specified input name. The namespace should be one of the special
|
||
|
constants produced by the uuid_ns_*() functions shown below. (It
|
||
|
could be any UUID in theory.) The name is an identifier in the
|
||
|
selected namespace. For example:
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org')</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
The name parameter will be MD5-hashed, so the cleartext cannot be
|
||
|
derived from the generated UUID.
|
||
|
</para>
|
||
|
<para>
|
||
|
The generation of UUIDs by this method has no random or
|
||
|
environment-dependent element and is therefore reproducible.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_generate_v4()</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
This function generates a version 4 UUID, which is derived entirely
|
||
|
from random numbers.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_generate_v5(namespace uuid, name text)</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
This function generates a version 5 UUID, which works like a version 3
|
||
|
UUID except that SHA-1 is used as a hashing method. Version 5 should
|
||
|
be preferred over version 3 because SHA-1 is thought to be more secure
|
||
|
than MD5.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
</tbody>
|
||
|
</tgroup>
|
||
|
</table>
|
||
|
|
||
|
<table>
|
||
|
<title>UUID Constants</title>
|
||
|
<tgroup cols="2">
|
||
|
<tbody>
|
||
|
<row>
|
||
|
<entry><literal>uuid_nil()</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
A "nil" UUID constant, which does not occur as a real UUID.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_ns_dns()</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
Constant designating the DNS namespace for UUIDs.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_ns_url()</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
Constant designating the URL namespace for UUIDs.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_ns_oid()</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
Constant designating the ISO object identifier (OID) namespace for
|
||
|
UUIDs. (This pertains to ASN.1 OIDs, unrelated to the OIDs used in
|
||
|
PostgreSQL.)
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry><literal>uuid_ns_x500()</literal></entry>
|
||
|
<entry>
|
||
|
<para>
|
||
|
Constant designating the X.500 distinguished name (DN) namespace for
|
||
|
UUIDs.
|
||
|
</para>
|
||
|
</entry>
|
||
|
</row>
|
||
|
</tbody>
|
||
|
</tgroup>
|
||
|
</table>
|
||
|
</sect2>
|
||
|
<sect2>
|
||
|
<title>Author</title>
|
||
|
<para>
|
||
|
Peter Eisentraut <email>peter_e@gmx.net</email>
|
||
|
</para>
|
||
|
</sect2>
|
||
|
</sect1>
|
||
|
|