|
| 1 | +UUID Generation Functions |
| 2 | +========================= |
| 3 | +Peter Eisentraut <peter_e@gmx.net> |
| 4 | + |
| 5 | +This module provides functions to generate universally unique |
| 6 | +identifiers (UUIDs) using one of the several standard algorithms, as |
| 7 | +well as functions to produce certain special UUID constants. |
| 8 | + |
| 9 | + |
| 10 | +Installation |
| 11 | +------------ |
| 12 | + |
| 13 | +The extra library required can be found at |
| 14 | +<http://www.ossp.org/pkg/lib/uuid/>. |
| 15 | + |
| 16 | + |
| 17 | +UUID Generation |
| 18 | +--------------- |
| 19 | + |
| 20 | +The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and RFC |
| 21 | +4122 specify four algorithms for generating UUIDs, identified by the |
| 22 | +version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.) |
| 23 | +Each of these algorithms could be suitable for a different set of |
| 24 | +applications. |
| 25 | + |
| 26 | +uuid_generate_v1() |
| 27 | +~~~~~~~~~~~~~~~~~~ |
| 28 | + |
| 29 | +This function generates a version 1 UUID. This involves the MAC |
| 30 | +address of the computer and a time stamp. Note that UUIDs of this |
| 31 | +kind reveal the identity of the computer that created the identifier |
| 32 | +and the time at which it did so, which might make it unsuitable for |
| 33 | +certain security-sensitive applications. |
| 34 | + |
| 35 | +uuid_generate_v1mc() |
| 36 | +~~~~~~~~~~~~~~~~~~~~ |
| 37 | + |
| 38 | +This function generates a version 1 UUID but uses a random multicast |
| 39 | +MAC address instead of the real MAC address of the computer. |
| 40 | + |
| 41 | +uuid_generate_v3(namespace uuid, name text) |
| 42 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 43 | + |
| 44 | +This function generates a version 3 UUID in the given namespace using |
| 45 | +the specified input name. The namespace should be one of the special |
| 46 | +constants produced by the uuid_ns_*() functions shown below. (It |
| 47 | +should be any UUID in theory.) The name is an identifier in the |
| 48 | +selected namespace. For example: |
| 49 | + |
| 50 | + uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org') |
| 51 | + |
| 52 | +The name parameter will be MD5-hashed, so the cleartext cannot be |
| 53 | +derived from the generated UUID. |
| 54 | + |
| 55 | +The generation of UUIDs by this method has no random or |
| 56 | +environment-dependent element and is therefore reproducible. |
| 57 | + |
| 58 | +uuid_generate_v4() |
| 59 | +~~~~~~~~~~~~~~~~~~ |
| 60 | + |
| 61 | +This function generates a version 4 UUID, which is derived entirely |
| 62 | +from random numbers. |
| 63 | + |
| 64 | +uuid_generate_v5(namespace uuid, name text) |
| 65 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 66 | + |
| 67 | +This function generates a version 5 UUID, which works like a version 3 |
| 68 | +UUID except that SHA-1 is used as a hashing method. Version 5 should |
| 69 | +be preferred over version 3 because SHA-1 is thought to be more secure |
| 70 | +than MD5. |
| 71 | + |
| 72 | + |
| 73 | +UUID Constants |
| 74 | +-------------- |
| 75 | + |
| 76 | + uuid_nil() |
| 77 | + |
| 78 | +A "nil" UUID constant, which does not occur as a real UUID. |
| 79 | + |
| 80 | + uuid_ns_dns() |
| 81 | + |
| 82 | +Constant designating the DNS namespace for UUIDs. |
| 83 | + |
| 84 | + uuid_ns_url() |
| 85 | + |
| 86 | +Constant designating the URL namespace for UUIDs. |
| 87 | + |
| 88 | + uuid_ns_oid() |
| 89 | + |
| 90 | +Constant designating the ISO object identifier (OID) namespace for |
| 91 | +UUIDs. (This pertains to ASN.1 OIDs, unrelated to the OIDs used in |
| 92 | +PostgreSQL.) |
| 93 | + |
| 94 | + uuid_ns_x500() |
| 95 | + |
| 96 | +Constant designating the X.500 distinguished name (DN) namespace for |
| 97 | +UUIDs. |
0 commit comments