1<!-- doc/src/sgml/uuid-ossp.sgml --> 2 3<sect1 id="uuid-ossp" xreflabel="uuid-ossp"> 4 <title>uuid-ossp</title> 5 6 <indexterm zone="uuid-ossp"> 7 <primary>uuid-ossp</primary> 8 </indexterm> 9 10 <para> 11 The <filename>uuid-ossp</filename> module provides functions to generate universally 12 unique identifiers (UUIDs) using one of several standard algorithms. There 13 are also functions to produce certain special UUID constants. 14 This module is only necessary for special requirements beyond what is 15 available in core <productname>PostgreSQL</productname>. See <xref 16 linkend="functions-uuid"/> for built-in ways to generate UUIDs. 17 </para> 18 19 <para> 20 This module is considered <quote>trusted</quote>, that is, it can be 21 installed by non-superusers who have <literal>CREATE</literal> privilege 22 on the current database. 23 </para> 24 25 <sect2> 26 <title><literal>uuid-ossp</literal> Functions</title> 27 28 <para> 29 <xref linkend="uuid-ossp-functions"/> shows the functions available to 30 generate UUIDs. 31 The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and RFC 32 4122 specify four algorithms for generating UUIDs, identified by the 33 version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.) 34 Each of these algorithms could be suitable for a different set of 35 applications. 36 </para> 37 38 <table id="uuid-ossp-functions"> 39 <title>Functions for UUID Generation</title> 40 <tgroup cols="1"> 41 <thead> 42 <row> 43 <entry role="func_table_entry"><para role="func_signature"> 44 Function 45 </para> 46 <para> 47 Description 48 </para></entry> 49 </row> 50 </thead> 51 52 <tbody> 53 <row> 54 <entry role="func_table_entry"><para role="func_signature"> 55 <indexterm><primary>uuid_generate_v1</primary></indexterm> 56 <function>uuid_generate_v1</function> () 57 <returnvalue>uuid</returnvalue> 58 </para> 59 <para> 60 Generates a version 1 UUID. This involves the MAC 61 address of the computer and a time stamp. Note that UUIDs of this 62 kind reveal the identity of the computer that created the identifier 63 and the time at which it did so, which might make it unsuitable for 64 certain security-sensitive applications. 65 </para></entry> 66 </row> 67 68 <row> 69 <entry role="func_table_entry"><para role="func_signature"> 70 <indexterm><primary>uuid_generate_v1mc</primary></indexterm> 71 <function>uuid_generate_v1mc</function> () 72 <returnvalue>uuid</returnvalue> 73 </para> 74 <para> 75 Generates a version 1 UUID, but uses a random multicast 76 MAC address instead of the real MAC address of the computer. 77 </para></entry> 78 </row> 79 80 <row> 81 <entry role="func_table_entry"><para role="func_signature"> 82 <indexterm><primary>uuid_generate_v3</primary></indexterm> 83 <function>uuid_generate_v3</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> ) 84 <returnvalue>uuid</returnvalue> 85 </para> 86 <para> 87 Generates a version 3 UUID in the given namespace using 88 the specified input name. The namespace should be one of the special 89 constants produced by the <function>uuid_ns_*()</function> functions 90 shown in <xref linkend="uuid-ossp-constants"/>. (It could be any UUID 91 in theory.) The name is an identifier in the selected namespace. 92 </para> 93 <para> 94 For example: 95 96<programlisting> 97SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org'); 98</programlisting> 99 100 The name parameter will be MD5-hashed, so the cleartext cannot be 101 derived from the generated UUID. 102 The generation of UUIDs by this method has no random or 103 environment-dependent element and is therefore reproducible. 104 </para></entry> 105 </row> 106 107 <row> 108 <entry role="func_table_entry"><para role="func_signature"> 109 <function>uuid_generate_v4</function> () 110 <returnvalue>uuid</returnvalue> 111 </para> 112 <para> 113 Generates a version 4 UUID, which is derived entirely 114 from random numbers. 115 </para></entry> 116 </row> 117 118 <row> 119 <entry role="func_table_entry"><para role="func_signature"> 120 <function>uuid_generate_v5</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> ) 121 <returnvalue>uuid</returnvalue> 122 </para> 123 <para> 124 Generates a version 5 UUID, which works like a version 3 125 UUID except that SHA-1 is used as a hashing method. Version 5 should 126 be preferred over version 3 because SHA-1 is thought to be more secure 127 than MD5. 128 </para></entry> 129 </row> 130 </tbody> 131 </tgroup> 132 </table> 133 134 <table id="uuid-ossp-constants"> 135 <title>Functions Returning UUID Constants</title> 136 <tgroup cols="1"> 137 <thead> 138 <row> 139 <entry role="func_table_entry"><para role="func_signature"> 140 Function 141 </para> 142 <para> 143 Description 144 </para></entry> 145 </row> 146 </thead> 147 148 <tbody> 149 <row> 150 <entry role="func_table_entry"><para role="func_signature"> 151 <function>uuid_nil</function> () 152 <returnvalue>uuid</returnvalue> 153 </para> 154 <para> 155 Returns a <quote>nil</quote> UUID constant, which does not occur as a 156 real UUID. 157 </para></entry> 158 </row> 159 160 <row> 161 <entry role="func_table_entry"><para role="func_signature"> 162 <function>uuid_ns_dns</function> () 163 <returnvalue>uuid</returnvalue> 164 </para> 165 <para> 166 Returns a constant designating the DNS namespace for UUIDs. 167 </para></entry> 168 </row> 169 170 <row> 171 <entry role="func_table_entry"><para role="func_signature"> 172 <function>uuid_ns_url</function> () 173 <returnvalue>uuid</returnvalue> 174 </para> 175 <para> 176 Returns a constant designating the URL namespace for UUIDs. 177 </para></entry> 178 </row> 179 180 <row> 181 <entry role="func_table_entry"><para role="func_signature"> 182 <function>uuid_ns_oid</function> () 183 <returnvalue>uuid</returnvalue> 184 </para> 185 <para> 186 Returns a constant designating the ISO object identifier (OID) namespace for 187 UUIDs. (This pertains to ASN.1 OIDs, which are unrelated to the OIDs 188 used in <productname>PostgreSQL</productname>.) 189 </para></entry> 190 </row> 191 192 <row> 193 <entry role="func_table_entry"><para role="func_signature"> 194 <function>uuid_ns_x500</function> () 195 <returnvalue>uuid</returnvalue> 196 </para> 197 <para> 198 Returns a constant designating the X.500 distinguished name (DN) 199 namespace for UUIDs. 200 </para></entry> 201 </row> 202 </tbody> 203 </tgroup> 204 </table> 205 </sect2> 206 207 <sect2> 208 <title>Building <filename>uuid-ossp</filename></title> 209 210 <para> 211 Historically this module depended on the OSSP UUID library, which accounts 212 for the module's name. While the OSSP UUID library can still be found 213 at <ulink url="http://www.ossp.org/pkg/lib/uuid/"></ulink>, it is not well 214 maintained, and is becoming increasingly difficult to port to newer 215 platforms. <filename>uuid-ossp</filename> can now be built without the OSSP 216 library on some platforms. On FreeBSD, NetBSD, and some other BSD-derived 217 platforms, suitable UUID creation functions are included in the 218 core <filename>libc</filename> library. On Linux, macOS, and some other 219 platforms, suitable functions are provided in the <filename>libuuid</filename> 220 library, which originally came from the <literal>e2fsprogs</literal> project 221 (though on modern Linux it is considered part 222 of <literal>util-linux-ng</literal>). When invoking <filename>configure</filename>, 223 specify <option>--with-uuid=bsd</option> to use the BSD functions, 224 or <option>--with-uuid=e2fs</option> to 225 use <literal>e2fsprogs</literal>' <filename>libuuid</filename>, or 226 <option>--with-uuid=ossp</option> to use the OSSP UUID library. 227 More than one of these libraries might be available on a particular 228 machine, so <filename>configure</filename> does not automatically choose one. 229 </para> 230 </sect2> 231 232 <sect2> 233 <title>Author</title> 234 235 <para> 236 Peter Eisentraut <email>peter_e@gmx.net</email> 237 </para> 238 239 </sect2> 240 241</sect1> 242