uuid-ossp

The uuid-ossp module provides functions to generate Universally Unique Identifiers (UUIDs) using one of several standard algorithms. It also provides functions to produce certain special UUID constants. This module is intended for specialized requirements beyond what is provided in the core Halo system. This module is considered "trusted", that is, it can be installed by non-superusers who have CREATE privilege on the current database.

1. uuid-ossp Functions

Table C.32 shows the functions available for generating UUIDs. The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and RFC 4122 specify four algorithms for generating UUIDs, identified by version numbers 1, 3, 4, and 5 (there is no version 2 algorithm). Each of these algorithms is suitable for a different set of applications.

Table C.32. Functions for UUID Generation

Function/Brief
uuid_generate_v1 () → uuid Generates a version 1 UUID. This involves the computer's MAC address and a timestamp. Note that this UUID may leak the identity of the computer that generated the identifier and the time of generation, so it may not be suitable for some security-sensitive applications.
uuid_generate_v1mc () → uuid This function generates a version 1 UUID, but uses a random broadcast MAC address instead of the computer's real MAC address.
uuid_generate_v3 ( namespace uuid, name text ) → uuid 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 (as shown in Table C.33) (theoretically it could be any UUID). The name is an identifier in the chosen namespace. For example: SELECT uuid_generate_v3(uuid_ns_url(), 'http://example.com'); The name parameter will be hashed using MD5, so the plaintext cannot be recovered from the resulting UUID. UUID generation using this method has no randomness and does not involve environment-dependent elements, so it is reproducible.
uuid_generate_v4 () → uuid Generates a version 4 UUID, which is entirely based on random numbers.
uuid_generate_v5 ( namespace uuid, name text ) → uuid Generates a version 5 UUID, which is similar to a version 3 UUID but uses SHA-1 as the hashing method. Version 5 is preferable to version 3 because SHA-1 is considered more secure than MD5.

Table C.33. Functions Returning UUID Constants

Function/Brief
uuid_nil () → uuid Returns a "nil" UUID constant, which does not appear as a real UUID.
uuid_ns_dns () → uuid Returns the constant designating the DNS namespace for UUIDs.
uuid_ns_url () → uuid Returns the constant designating the URL namespace for UUIDs.
uuid_ns_oid () → uuid Returns the constant designating the ISO Object Identifier (OID) namespace for UUIDs (this refers to ASN.1 OIDs, which are unrelated to the OIDs used in PostgreSQL).
uuid_ns_x500 () → uuid Returns the constant designating the X.500 Distinguished Name (DN) namespace for UUIDs.

2. Building uuid-ossp

Historically, this module depended on the OSSP UUID library, which is the origin of the module name. uuid-ossp can now be compiled without the OSSP library on some platforms.

On FreeBSD, NetBSD, and some other BSD-derived platforms, suitable UUID creation functions are already included in the core libc library. On Linux, macOS, and some other platforms, suitable functions are provided by the libuuid library, which originally came from the e2fsprogs project (though on modern Linux it is considered part of util-linux-ng). When invoking configure, specify --with-uuid=bsd to use BSD functions, --with-uuid=e2fs to use e2fsprogs' libuuid, or --with-uuid=ossp to use the OSSP UUID library.

Multiple libraries may exist on a particular machine, so configure will not automatically select one of them.