begriffs open source - ai-pg/blob - full-docs/html/pgcrypto.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.26. pgcrypto — cryptographic functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgbuffercache.html" title="F.25. pg_buffercache — inspect PostgreSQL buffer cache state" /><link rel="next" href="pgfreespacemap.html" title="F.27. pg_freespacemap — examine the free space map" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.26. pgcrypto — cryptographic functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgbuffercache.html" title="F.25. pg_buffercache — inspect PostgreSQL&#10;    buffer cache state">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules and Extensions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgfreespacemap.html" title="F.27. pg_freespacemap — examine the free space map">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGCRYPTO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.26. pgcrypto — cryptographic functions <a href="#PGCRYPTO" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-GENERAL-HASHING-FUNCS">F.26.1. General Hashing Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-PASSWORD-HASHING-FUNCS">F.26.2. Password Hashing Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-PGP-ENC-FUNCS">F.26.3. PGP Encryption Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-RAW-ENC-FUNCS">F.26.4. Raw Encryption Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-RANDOM-DATA-FUNCS">F.26.5. Random-Data Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-OPENSSL-SUPPORT-FUNCS">F.26.6. OpenSSL Support Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-CONFIGURATION-PARAMETERS">F.26.7. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-NOTES">F.26.8. Notes</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#PGCRYPTO-AUTHOR">F.26.9. Author</a></span></dt></dl></div><a id="id-1.11.7.36.2" class="indexterm"></a><a id="id-1.11.7.36.3" class="indexterm"></a><p>
   3   The <code class="filename">pgcrypto</code> module provides cryptographic functions for
   4   <span class="productname">PostgreSQL</span>.
   5  </p><p>
   6   This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
   7   installed by non-superusers who have <code class="literal">CREATE</code> privilege
   8   on the current database.
   9  </p><p>
  10   <code class="filename">pgcrypto</code> requires OpenSSL and won't be installed if
  11   OpenSSL support was not selected when PostgreSQL was built.
  12  </p><div class="sect2" id="PGCRYPTO-GENERAL-HASHING-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.26.1. General Hashing Functions <a href="#PGCRYPTO-GENERAL-HASHING-FUNCS" class="id_link">#</a></h3></div></div></div><div class="sect3" id="PGCRYPTO-GENERAL-HASHING-FUNCS-DIGEST"><div class="titlepage"><div><div><h4 class="title">F.26.1.1. <code class="function">digest()</code> <a href="#PGCRYPTO-GENERAL-HASHING-FUNCS-DIGEST" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.7.2.2" class="indexterm"></a><pre class="synopsis">
  13 digest(data text, type text) returns bytea
  14 digest(data bytea, type text) returns bytea
  15 </pre><p>
  16     Computes a binary hash of the given <em class="parameter"><code>data</code></em>.
  17     <em class="parameter"><code>type</code></em> is the algorithm to use.
  18     Standard algorithms are <code class="literal">md5</code>, <code class="literal">sha1</code>,
  19     <code class="literal">sha224</code>, <code class="literal">sha256</code>,
  20     <code class="literal">sha384</code> and <code class="literal">sha512</code>.
  21     Moreover, any digest algorithm <span class="productname">OpenSSL</span> supports
  22     is automatically picked up.
  23    </p><p>
  24     If you want the digest as a hexadecimal string, use
  25     <code class="function">encode()</code> on the result.  For example:
  26 </p><pre class="programlisting">
  27 CREATE OR REPLACE FUNCTION sha1(bytea) returns text AS $$
  28     SELECT encode(digest($1, 'sha1'), 'hex')
  29 $$ LANGUAGE SQL STRICT IMMUTABLE;
  30 </pre><p>
  31    </p></div><div class="sect3" id="PGCRYPTO-GENERAL-HASHING-FUNCS-HMAC"><div class="titlepage"><div><div><h4 class="title">F.26.1.2. <code class="function">hmac()</code> <a href="#PGCRYPTO-GENERAL-HASHING-FUNCS-HMAC" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.7.3.2" class="indexterm"></a><pre class="synopsis">
  32 hmac(data text, key text, type text) returns bytea
  33 hmac(data bytea, key bytea, type text) returns bytea
  34 </pre><p>
  35     Calculates hashed MAC for <em class="parameter"><code>data</code></em> with key <em class="parameter"><code>key</code></em>.
  36     <em class="parameter"><code>type</code></em> is the same as in <code class="function">digest()</code>.
  37    </p><p>
  38     This is similar to <code class="function">digest()</code> but the hash can only be
  39     recalculated knowing the key.  This prevents the scenario of someone
  40     altering data and also changing the hash to match.
  41    </p><p>
  42     If the key is larger than the hash block size it will first be hashed and
  43     the result will be used as key.
  44    </p></div></div><div class="sect2" id="PGCRYPTO-PASSWORD-HASHING-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.26.2. Password Hashing Functions <a href="#PGCRYPTO-PASSWORD-HASHING-FUNCS" class="id_link">#</a></h3></div></div></div><p>
  45    The functions <code class="function">crypt()</code> and <code class="function">gen_salt()</code>
  46    are specifically designed for hashing passwords.
  47    <code class="function">crypt()</code> does the hashing and <code class="function">gen_salt()</code>
  48    prepares algorithm parameters for it.
  49   </p><p>
  50    The algorithms in <code class="function">crypt()</code> differ from the usual
  51    MD5 or SHA-1 hashing algorithms in the following respects:
  52   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
  53      They are slow.  As the amount of data is so small, this is the only
  54      way to make brute-forcing passwords hard.
  55     </p></li><li class="listitem"><p>
  56      They use a random value, called the <em class="firstterm">salt</em>, so that users
  57      having the same password will have different encrypted passwords.
  58      This is also an additional defense against reversing the algorithm.
  59     </p></li><li class="listitem"><p>
  60      They include the algorithm type in the result, so passwords hashed with
  61      different algorithms can co-exist.
  62     </p></li><li class="listitem"><p>
  63      Some of them are adaptive — that means when computers get
  64      faster, you can tune the algorithm to be slower, without
  65      introducing incompatibility with existing passwords.
  66     </p></li></ol></div><p>
  67    <a class="xref" href="pgcrypto.html#PGCRYPTO-CRYPT-ALGORITHMS" title="Table F.18. Supported Algorithms for crypt()">Table F.18</a> lists the algorithms
  68    supported by the <code class="function">crypt()</code> function.
  69   </p><div class="table" id="PGCRYPTO-CRYPT-ALGORITHMS"><p class="title"><strong>Table F.18. Supported Algorithms for <code class="function">crypt()</code></strong></p><div class="table-contents"><table class="table" summary="Supported Algorithms for crypt()" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /><col class="col6" /></colgroup><thead><tr><th>Algorithm</th><th>Max Password Length</th><th>Adaptive?</th><th>Salt Bits</th><th>Output Length</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">bf</code></td><td>72</td><td>yes</td><td>128</td><td>60</td><td>Blowfish-based, variant 2a</td></tr><tr><td><code class="literal">md5</code></td><td>unlimited</td><td>no</td><td>48</td><td>34</td><td>MD5-based crypt</td></tr><tr><td><code class="literal">xdes</code></td><td>8</td><td>yes</td><td>24</td><td>20</td><td>Extended DES</td></tr><tr><td><code class="literal">des</code></td><td>8</td><td>no</td><td>12</td><td>13</td><td>Original UNIX crypt</td></tr><tr><td><code class="literal">sha256crypt</code></td><td>unlimited</td><td>yes</td><td>up to 32</td><td>80</td><td>Adapted from publicly available reference implementation
  70        <a class="ulink" href="https://www.akkadia.org/drepper/SHA-crypt.txt" target="_top">Unix crypt using SHA-256 and SHA-512
  71        </a>
  72       </td></tr><tr><td><code class="literal">sha512crypt</code></td><td>unlimited</td><td>yes</td><td>up to 32</td><td>123</td><td>Adapted from publicly available reference implementation
  73        <a class="ulink" href="https://www.akkadia.org/drepper/SHA-crypt.txt" target="_top">Unix crypt using SHA-256 and SHA-512
  74        </a>
  75       </td></tr></tbody></table></div></div><br class="table-break" /><div class="sect3" id="PGCRYPTO-PASSWORD-HASHING-FUNCS-CRYPT"><div class="titlepage"><div><div><h4 class="title">F.26.2.1. <code class="function">crypt()</code> <a href="#PGCRYPTO-PASSWORD-HASHING-FUNCS-CRYPT" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.8.7.2" class="indexterm"></a><pre class="synopsis">
  76 crypt(password text, salt text) returns text
  77 </pre><p>
  78     Calculates a crypt(3)-style hash of <em class="parameter"><code>password</code></em>.
  79     When storing a new password, you need to use
  80     <code class="function">gen_salt()</code> to generate a new <em class="parameter"><code>salt</code></em> value.
  81     To check a password, pass the stored hash value as <em class="parameter"><code>salt</code></em>,
  82     and test whether the result matches the stored value.
  83    </p><p>
  84     Example of setting a new password:
  85 </p><pre class="programlisting">
  86 UPDATE ... SET pswhash = crypt('new password', gen_salt('md5'));
  87 </pre><p>
  88    </p><p>
  89     Example of authentication:
  90 </p><pre class="programlisting">
  91 SELECT (pswhash = crypt('entered password', pswhash)) AS pswmatch FROM ... ;
  92 </pre><p>
  93     This returns <code class="literal">true</code> if the entered password is correct.
  94    </p></div><div class="sect3" id="PGCRYPTO-PASSWORD-HASHING-FUNCS-GEN-SALT"><div class="titlepage"><div><div><h4 class="title">F.26.2.2. <code class="function">gen_salt()</code> <a href="#PGCRYPTO-PASSWORD-HASHING-FUNCS-GEN-SALT" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.8.8.2" class="indexterm"></a><pre class="synopsis">
  95 gen_salt(type text [, iter_count integer ]) returns text
  96 </pre><p>
  97     Generates a new random salt string for use in <code class="function">crypt()</code>.
  98     The salt string also tells <code class="function">crypt()</code> which algorithm to use.
  99    </p><p>
 100     The <em class="parameter"><code>type</code></em> parameter specifies the hashing algorithm.
 101     The accepted types are: <code class="literal">des</code>, <code class="literal">xdes</code>,
 102     <code class="literal">md5</code>, <code class="literal">bf</code>, <code class="literal">sha256crypt</code> and
 103     <code class="literal">sha512crypt</code>. The last two, <code class="literal">sha256crypt</code> and
 104     <code class="literal">sha512crypt</code> are modern <code class="literal">SHA-2</code> based password hashes.
 105    </p><p>
 106     The <em class="parameter"><code>iter_count</code></em> parameter lets the user specify the iteration
 107     count, for algorithms that have one.
 108     The higher the count, the more time it takes to hash
 109     the password and therefore the more time to break it.  Although with
 110     too high a count the time to calculate a hash may be several years
 111     — which is somewhat impractical.  If the <em class="parameter"><code>iter_count</code></em>
 112     parameter is omitted, the default iteration count is used.
 113     Allowed values for <em class="parameter"><code>iter_count</code></em> depend on the algorithm and
 114     are shown in <a class="xref" href="pgcrypto.html#PGCRYPTO-ICFC-TABLE" title="Table F.19. Iteration Counts for crypt()">Table F.19</a>.
 115    </p><div class="table" id="PGCRYPTO-ICFC-TABLE"><p class="title"><strong>Table F.19. Iteration Counts for <code class="function">crypt()</code></strong></p><div class="table-contents"><table class="table" summary="Iteration Counts for crypt()" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Algorithm</th><th>Default</th><th>Min</th><th>Max</th></tr></thead><tbody><tr><td><code class="literal">xdes</code></td><td>725</td><td>1</td><td>16777215</td></tr><tr><td><code class="literal">bf</code></td><td>6</td><td>4</td><td>31</td></tr><tr><td><code class="literal">sha256crypt, sha512crypt</code></td><td>5000</td><td>1000</td><td>999999999</td></tr></tbody></table></div></div><br class="table-break" /><p>
 116     For <code class="literal">xdes</code> there is an additional limitation that the
 117     iteration count must be an odd number.
 118    </p><p>
 119     To pick an appropriate iteration count, consider that
 120     the original DES crypt was designed to have the speed of 4 hashes per
 121     second on the hardware of that time.
 122     Slower than 4 hashes per second would probably dampen usability.
 123     Faster than 100 hashes per second is probably too fast.
 124    </p><p>
 125     <a class="xref" href="pgcrypto.html#PGCRYPTO-HASH-SPEED-TABLE" title="Table F.20. Hash Algorithm Speeds">Table F.20</a> gives an overview of the relative slowness
 126     of different hashing algorithms.
 127     The table shows how much time it would take to try all
 128     combinations of characters in an 8-character password, assuming
 129     that the password contains either only lower case letters, or
 130     upper- and lower-case letters and numbers.
 131     In the <code class="literal">crypt-bf</code> entries, the number after a slash is
 132     the <em class="parameter"><code>iter_count</code></em> parameter of
 133     <code class="function">gen_salt</code>.
 134    </p><p>
 135    The default <em class="parameter"><code>iter_count</code></em> for <code class="literal">sha256crypt</code> and
 136    <code class="literal">sha512crypt</code> of <code class="literal">5000</code> is considered too low for modern
 137    hardware, but can be adjusted to generate stronger password hashes.
 138    Otherwise both hashes, <code class="literal">sha256crypt</code> and <code class="literal">sha512crypt</code> are
 139    considered safe.
 140    </p><div class="table" id="PGCRYPTO-HASH-SPEED-TABLE"><p class="title"><strong>Table F.20. Hash Algorithm Speeds</strong></p><div class="table-contents"><table class="table" summary="Hash Algorithm Speeds" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Algorithm</th><th>Hashes/sec</th><th>For <code class="literal">[a-z]</code></th><th>For <code class="literal">[A-Za-z0-9]</code></th><th>Duration relative to <code class="literal">md5 hash</code></th></tr></thead><tbody><tr><td><code class="literal">crypt-bf/8</code></td><td>1792</td><td>4 years</td><td>3927 years</td><td>100k</td></tr><tr><td><code class="literal">crypt-bf/7</code></td><td>3648</td><td>2 years</td><td>1929 years</td><td>50k</td></tr><tr><td><code class="literal">crypt-bf/6</code></td><td>7168</td><td>1 year</td><td>982 years</td><td>25k</td></tr><tr><td><code class="literal">crypt-bf/5</code></td><td>13504</td><td>188 days</td><td>521 years</td><td>12.5k</td></tr><tr><td><code class="literal">crypt-md5</code></td><td>171584</td><td>15 days</td><td>41 years</td><td>1k</td></tr><tr><td><code class="literal">crypt-des</code></td><td>23221568</td><td>157.5 minutes</td><td>108 days</td><td>7</td></tr><tr><td><code class="literal">sha1</code></td><td>37774272</td><td>90 minutes</td><td>68 days</td><td>4</td></tr><tr><td><code class="literal">md5</code> (hash)</td><td>150085504</td><td>22.5 minutes</td><td>17 days</td><td>1</td></tr></tbody></table></div></div><br class="table-break" /><p>
 141     Notes:
 142    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 143      The machine used is an Intel Mobile Core i3.
 144      </p></li><li class="listitem"><p>
 145       <code class="literal">crypt-des</code> and <code class="literal">crypt-md5</code> algorithm numbers are
 146       taken from John the Ripper v1.6.38 <code class="literal">-test</code> output.
 147      </p></li><li class="listitem"><p>
 148       <code class="literal">md5 hash</code> numbers are from mdcrack 1.2.
 149      </p></li><li class="listitem"><p>
 150       <code class="literal">sha1</code> numbers are from lcrack-20031130-beta.
 151      </p></li><li class="listitem"><p>
 152       <code class="literal">crypt-bf</code> numbers are taken using a simple program that
 153       loops over 1000 8-character passwords.  That way the speed
 154       with different numbers of iterations can be shown.  For reference: <code class="literal">john
 155       -test</code> shows 13506 loops/sec for <code class="literal">crypt-bf/5</code>.
 156       (The very small
 157       difference in results is in accordance with the fact that the
 158       <code class="literal">crypt-bf</code> implementation in <code class="filename">pgcrypto</code>
 159       is the same one used in John the Ripper.)
 160      </p></li></ul></div><p>
 161     Note that <span class="quote">“<span class="quote">try all combinations</span>”</span> is not a realistic exercise.
 162     Usually password cracking is done with the help of dictionaries, which
 163     contain both regular words and various mutations of them.  So, even
 164     somewhat word-like passwords could be cracked much faster than the above
 165     numbers suggest, while a 6-character non-word-like password may escape
 166     cracking.  Or not.
 167    </p></div></div><div class="sect2" id="PGCRYPTO-PGP-ENC-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.26.3. PGP Encryption Functions <a href="#PGCRYPTO-PGP-ENC-FUNCS" class="id_link">#</a></h3></div></div></div><p>
 168    The functions here implement the encryption part of the OpenPGP
 169    (<a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc4880" target="_top">RFC 4880</a>)
 170    standard.  Supported are both symmetric-key and public-key encryption.
 171   </p><p>
 172    An encrypted PGP message consists of 2 parts, or <em class="firstterm">packets</em>:
 173   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 174      Packet containing a session key — either symmetric-key or public-key
 175      encrypted.
 176     </p></li><li class="listitem"><p>
 177      Packet containing data encrypted with the session key.
 178     </p></li></ul></div><p>
 179    When encrypting with a symmetric key (i.e., a password):
 180   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
 181      The given password is hashed using a String2Key (S2K) algorithm.  This is
 182      rather similar to <code class="function">crypt()</code> algorithms — purposefully
 183      slow and with random salt — but it produces a full-length binary
 184      key.
 185     </p></li><li class="listitem"><p>
 186      If a separate session key is requested, a new random key will be
 187      generated.  Otherwise the S2K key will be used directly as the session
 188      key.
 189     </p></li><li class="listitem"><p>
 190      If the S2K key is to be used directly, then only S2K settings will be put
 191      into the session key packet.  Otherwise the session key will be encrypted
 192      with the S2K key and put into the session key packet.
 193     </p></li></ol></div><p>
 194    When encrypting with a public key:
 195   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
 196      A new random session key is generated.
 197     </p></li><li class="listitem"><p>
 198      It is encrypted using the public key and put into the session key packet.
 199     </p></li></ol></div><p>
 200    In either case the data to be encrypted is processed as follows:
 201   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
 202      Optional data-manipulation: compression, conversion to UTF-8,
 203      and/or conversion of line-endings.
 204     </p></li><li class="listitem"><p>
 205      The data is prefixed with a block of random bytes.  This is equivalent
 206      to using a random IV.
 207     </p></li><li class="listitem"><p>
 208      A SHA-1 hash of the random prefix and data is appended.
 209     </p></li><li class="listitem"><p>
 210      All this is encrypted with the session key and placed in the data packet.
 211     </p></li></ol></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-PGP-SYM-ENCRYPT"><div class="titlepage"><div><div><h4 class="title">F.26.3.1. <code class="function">pgp_sym_encrypt()</code> <a href="#PGCRYPTO-PGP-ENC-FUNCS-PGP-SYM-ENCRYPT" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.9.11.2" class="indexterm"></a><a id="id-1.11.7.36.9.11.3" class="indexterm"></a><pre class="synopsis">
 212 pgp_sym_encrypt(data text, psw text [, options text ]) returns bytea
 213 pgp_sym_encrypt_bytea(data bytea, psw text [, options text ]) returns bytea
 214 </pre><p>
 215     Encrypt <em class="parameter"><code>data</code></em> with a symmetric PGP key <em class="parameter"><code>psw</code></em>.
 216     The <em class="parameter"><code>options</code></em> parameter can contain option settings,
 217     as described below.
 218    </p></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-PGP-SYM-DECRYPT"><div class="titlepage"><div><div><h4 class="title">F.26.3.2. <code class="function">pgp_sym_decrypt()</code> <a href="#PGCRYPTO-PGP-ENC-FUNCS-PGP-SYM-DECRYPT" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.9.12.2" class="indexterm"></a><a id="id-1.11.7.36.9.12.3" class="indexterm"></a><pre class="synopsis">
 219 pgp_sym_decrypt(msg bytea, psw text [, options text ]) returns text
 220 pgp_sym_decrypt_bytea(msg bytea, psw text [, options text ]) returns bytea
 221 </pre><p>
 222     Decrypt a symmetric-key-encrypted PGP message.
 223    </p><p>
 224     Decrypting <code class="type">bytea</code> data with <code class="function">pgp_sym_decrypt</code> is disallowed.
 225     This is to avoid outputting invalid character data.  Decrypting
 226     originally textual data with <code class="function">pgp_sym_decrypt_bytea</code> is fine.
 227    </p><p>
 228     The <em class="parameter"><code>options</code></em> parameter can contain option settings,
 229     as described below.
 230    </p></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-PGP-PUB-ENCRYPT"><div class="titlepage"><div><div><h4 class="title">F.26.3.3. <code class="function">pgp_pub_encrypt()</code> <a href="#PGCRYPTO-PGP-ENC-FUNCS-PGP-PUB-ENCRYPT" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.9.13.2" class="indexterm"></a><a id="id-1.11.7.36.9.13.3" class="indexterm"></a><pre class="synopsis">
 231 pgp_pub_encrypt(data text, key bytea [, options text ]) returns bytea
 232 pgp_pub_encrypt_bytea(data bytea, key bytea [, options text ]) returns bytea
 233 </pre><p>
 234     Encrypt <em class="parameter"><code>data</code></em> with a public PGP key <em class="parameter"><code>key</code></em>.
 235     Giving this function a secret key will produce an error.
 236    </p><p>
 237     The <em class="parameter"><code>options</code></em> parameter can contain option settings,
 238     as described below.
 239    </p></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-PGP-PUB-DECRYPT"><div class="titlepage"><div><div><h4 class="title">F.26.3.4. <code class="function">pgp_pub_decrypt()</code> <a href="#PGCRYPTO-PGP-ENC-FUNCS-PGP-PUB-DECRYPT" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.9.14.2" class="indexterm"></a><a id="id-1.11.7.36.9.14.3" class="indexterm"></a><pre class="synopsis">
 240 pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text ]]) returns text
 241 pgp_pub_decrypt_bytea(msg bytea, key bytea [, psw text [, options text ]]) returns bytea
 242 </pre><p>
 243     Decrypt a public-key-encrypted message.  <em class="parameter"><code>key</code></em> must be the
 244     secret key corresponding to the public key that was used to encrypt.
 245     If the secret key is password-protected, you must give the password in
 246     <em class="parameter"><code>psw</code></em>.  If there is no password, but you want to specify
 247     options, you need to give an empty password.
 248    </p><p>
 249     Decrypting <code class="type">bytea</code> data with <code class="function">pgp_pub_decrypt</code> is disallowed.
 250     This is to avoid outputting invalid character data.  Decrypting
 251     originally textual data with <code class="function">pgp_pub_decrypt_bytea</code> is fine.
 252    </p><p>
 253     The <em class="parameter"><code>options</code></em> parameter can contain option settings,
 254     as described below.
 255    </p></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-PGP-KEY-ID"><div class="titlepage"><div><div><h4 class="title">F.26.3.5. <code class="function">pgp_key_id()</code> <a href="#PGCRYPTO-PGP-ENC-FUNCS-PGP-KEY-ID" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.9.15.2" class="indexterm"></a><pre class="synopsis">
 256 pgp_key_id(bytea) returns text
 257 </pre><p>
 258     <code class="function">pgp_key_id</code> extracts the key ID of a PGP public or secret key.
 259     Or it gives the key ID that was used for encrypting the data, if given
 260     an encrypted message.
 261    </p><p>
 262     It can return 2 special key IDs:
 263    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 264       <code class="literal">SYMKEY</code>
 265      </p><p>
 266       The message is encrypted with a symmetric key.
 267      </p></li><li class="listitem"><p>
 268       <code class="literal">ANYKEY</code>
 269      </p><p>
 270       The message is public-key encrypted, but the key ID has been removed.
 271       That means you will need to try all your secret keys on it to see
 272       which one decrypts it.  <code class="filename">pgcrypto</code> itself does not produce
 273       such messages.
 274      </p></li></ul></div><p>
 275     Note that different keys may have the same ID.   This is rare but a normal
 276     event. The client application should then try to decrypt with each one,
 277     to see which fits — like handling <code class="literal">ANYKEY</code>.
 278    </p></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-ARMOR"><div class="titlepage"><div><div><h4 class="title">F.26.3.6. <code class="function">armor()</code>, <code class="function">dearmor()</code> <a href="#PGCRYPTO-PGP-ENC-FUNCS-ARMOR" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.9.16.2" class="indexterm"></a><a id="id-1.11.7.36.9.16.3" class="indexterm"></a><pre class="synopsis">
 279 armor(data bytea [ , keys text[], values text[] ]) returns text
 280 dearmor(data text) returns bytea
 281 </pre><p>
 282     These functions wrap/unwrap binary data into PGP ASCII-armor format,
 283     which is basically Base64 with CRC and additional formatting.
 284    </p><p>
 285     If the <em class="parameter"><code>keys</code></em> and <em class="parameter"><code>values</code></em> arrays are specified,
 286     an <em class="firstterm">armor header</em> is added to the armored format for each
 287     key/value pair. Both arrays must be single-dimensional, and they must
 288     be of the same length.  The keys and values cannot contain any non-ASCII
 289     characters.
 290    </p></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-PGP-ARMOR-HEADERS"><div class="titlepage"><div><div><h4 class="title">F.26.3.7. <code class="function">pgp_armor_headers</code> <a href="#PGCRYPTO-PGP-ENC-FUNCS-PGP-ARMOR-HEADERS" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.36.9.17.2" class="indexterm"></a><pre class="synopsis">
 291 pgp_armor_headers(data text, key out text, value out text) returns setof record
 292 </pre><p>
 293     <code class="function">pgp_armor_headers()</code> extracts the armor headers from
 294     <em class="parameter"><code>data</code></em>.  The return value is a set of rows with two columns,
 295     key and value.  If the keys or values contain any non-ASCII characters,
 296     they are treated as UTF-8.
 297    </p></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS"><div class="titlepage"><div><div><h4 class="title">F.26.3.8. Options for PGP Functions <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS" class="id_link">#</a></h4></div></div></div><p>
 298     Options are named to be similar to GnuPG.  An option's value should be
 299     given after an equal sign; separate options from each other with commas.
 300     For example:
 301 </p><pre class="programlisting">
 302 pgp_sym_encrypt(data, psw, 'compress-algo=1, cipher-algo=aes256')
 303 </pre><p>
 304    </p><p>
 305     All of the options except <code class="literal">convert-crlf</code> apply only to
 306     encrypt functions.  Decrypt functions get the parameters from the PGP
 307     data.
 308    </p><p>
 309     The most interesting options are probably
 310     <code class="literal">compress-algo</code> and <code class="literal">unicode-mode</code>.
 311     The rest should have reasonable defaults.
 312    </p><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-CIPHER-ALGO"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.1. cipher-algo <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-CIPHER-ALGO" class="id_link">#</a></h5></div></div></div><p>
 313     Which cipher algorithm to use.
 314    </p><div class="literallayout"><p><br />
 315 Values: bf, aes128, aes192, aes256, 3des, cast5<br />
 316 Default: aes128<br />
 317 Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
 318 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-COMPRESS-ALGO"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.2. compress-algo <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-COMPRESS-ALGO" class="id_link">#</a></h5></div></div></div><p>
 319     Which compression algorithm to use.  Only available if
 320     <span class="productname">PostgreSQL</span> was built with zlib.
 321    </p><div class="literallayout"><p><br />
 322 Values:<br />
 323   0 - no compression<br />
 324   1 - ZIP compression<br />
 325   2 - ZLIB compression (= ZIP plus meta-data and block CRCs)<br />
 326 Default: 0<br />
 327 Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
 328 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-COMPRESS-LEVEL"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.3. compress-level <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-COMPRESS-LEVEL" class="id_link">#</a></h5></div></div></div><p>
 329     How much to compress.  Higher levels compress smaller but are slower.
 330     0 disables compression.
 331    </p><div class="literallayout"><p><br />
 332 Values: 0, 1-9<br />
 333 Default: 6<br />
 334 Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
 335 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-CONVERT-CRLF"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.4. convert-crlf <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-CONVERT-CRLF" class="id_link">#</a></h5></div></div></div><p>
 336     Whether to convert <code class="literal">\n</code> into <code class="literal">\r\n</code> when
 337     encrypting and <code class="literal">\r\n</code> to <code class="literal">\n</code> when
 338     decrypting.  <acronym class="acronym">RFC</acronym> 4880 specifies that text data should be stored using
 339     <code class="literal">\r\n</code> line-feeds.  Use this to get fully RFC-compliant
 340     behavior.
 341    </p><div class="literallayout"><p><br />
 342 Values: 0, 1<br />
 343 Default: 0<br />
 344 Applies to: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt<br />
 345 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-DISABLE-MDC"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.5. disable-mdc <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-DISABLE-MDC" class="id_link">#</a></h5></div></div></div><p>
 346     Do not protect data with SHA-1.  The only good reason to use this
 347     option is to achieve compatibility with ancient PGP products, predating
 348     the addition of SHA-1 protected packets to <acronym class="acronym">RFC</acronym> 4880.
 349     Recent gnupg.org and pgp.com software supports it fine.
 350    </p><div class="literallayout"><p><br />
 351 Values: 0, 1<br />
 352 Default: 0<br />
 353 Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
 354 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-SESS-KEY"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.6. sess-key <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-SESS-KEY" class="id_link">#</a></h5></div></div></div><p>
 355     Use separate session key.  Public-key encryption always uses a separate
 356     session key; this option is for symmetric-key encryption, which by default
 357     uses the S2K key directly.
 358    </p><div class="literallayout"><p><br />
 359 Values: 0, 1<br />
 360 Default: 0<br />
 361 Applies to: pgp_sym_encrypt<br />
 362 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-S2K-MODE"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.7. s2k-mode <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-S2K-MODE" class="id_link">#</a></h5></div></div></div><p>
 363     Which S2K algorithm to use.
 364    </p><div class="literallayout"><p><br />
 365 Values:<br />
 366   0 - Without salt.  Dangerous!<br />
 367   1 - With salt but with fixed iteration count.<br />
 368   3 - Variable iteration count.<br />
 369 Default: 3<br />
 370 Applies to: pgp_sym_encrypt<br />
 371 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-S2K-COUNT"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.8. s2k-count <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-S2K-COUNT" class="id_link">#</a></h5></div></div></div><p>
 372     The number of iterations of the S2K algorithm to use.  It must
 373     be a value between 1024 and 65011712, inclusive.
 374    </p><div class="literallayout"><p><br />
 375 Default: A random value between 65536 and 253952<br />
 376 Applies to: pgp_sym_encrypt, only with s2k-mode=3<br />
 377 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-S2K-DIGEST-ALGO"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.9. s2k-digest-algo <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-S2K-DIGEST-ALGO" class="id_link">#</a></h5></div></div></div><p>
 378     Which digest algorithm to use in S2K calculation.
 379    </p><div class="literallayout"><p><br />
 380 Values: md5, sha1<br />
 381 Default: sha1<br />
 382 Applies to: pgp_sym_encrypt<br />
 383 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-S2K-CIPHER-ALGO"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.10. s2k-cipher-algo <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-S2K-CIPHER-ALGO" class="id_link">#</a></h5></div></div></div><p>
 384     Which cipher to use for encrypting separate session key.
 385    </p><div class="literallayout"><p><br />
 386 Values: bf, aes, aes128, aes192, aes256<br />
 387 Default: use cipher-algo<br />
 388 Applies to: pgp_sym_encrypt<br />
 389 </p></div></div><div class="sect4" id="PGCRYPTO-PGP-ENC-FUNCS-OPTS-UNICODE-MODE"><div class="titlepage"><div><div><h5 class="title">F.26.3.8.11. unicode-mode <a href="#PGCRYPTO-PGP-ENC-FUNCS-OPTS-UNICODE-MODE" class="id_link">#</a></h5></div></div></div><p>
 390     Whether to convert textual data from database internal encoding to
 391     UTF-8 and back.  If your database already is UTF-8, no conversion will
 392     be done, but the message will be tagged as UTF-8.  Without this option
 393     it will not be.
 394    </p><div class="literallayout"><p><br />
 395 Values: 0, 1<br />
 396 Default: 0<br />
 397 Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
 398 </p></div></div></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-GNUPG"><div class="titlepage"><div><div><h4 class="title">F.26.3.9. Generating PGP Keys with GnuPG <a href="#PGCRYPTO-PGP-ENC-FUNCS-GNUPG" class="id_link">#</a></h4></div></div></div><p>
 399    To generate a new key:
 400 </p><pre class="programlisting">
 401 gpg --gen-key
 402 </pre><p>
 403   </p><p>
 404    The preferred key type is <span class="quote">“<span class="quote">DSA and Elgamal</span>”</span>.
 405   </p><p>
 406    For RSA encryption you must create either DSA or RSA sign-only key
 407    as master and then add an RSA encryption subkey with
 408    <code class="literal">gpg --edit-key</code>.
 409   </p><p>
 410    To list keys:
 411 </p><pre class="programlisting">
 412 gpg --list-secret-keys
 413 </pre><p>
 414   </p><p>
 415    To export a public key in ASCII-armor format:
 416 </p><pre class="programlisting">
 417 gpg -a --export KEYID &gt; public.key
 418 </pre><p>
 419   </p><p>
 420    To export a secret key in ASCII-armor format:
 421 </p><pre class="programlisting">
 422 gpg -a --export-secret-keys KEYID &gt; secret.key
 423 </pre><p>
 424   </p><p>
 425    You need to use <code class="function">dearmor()</code> on these keys before giving them to
 426    the PGP functions.  Or if you can handle binary data, you can drop
 427    <code class="literal">-a</code> from the command.
 428   </p><p>
 429    For more details see <code class="literal">man gpg</code>,
 430    <a class="ulink" href="https://www.gnupg.org/gph/en/manual.html" target="_top">The GNU
 431    Privacy Handbook</a> and other documentation on
 432    <a class="ulink" href="https://www.gnupg.org/" target="_top">https://www.gnupg.org/</a>.
 433   </p></div><div class="sect3" id="PGCRYPTO-PGP-ENC-FUNCS-LIMITATIONS"><div class="titlepage"><div><div><h4 class="title">F.26.3.10. Limitations of PGP Code <a href="#PGCRYPTO-PGP-ENC-FUNCS-LIMITATIONS" class="id_link">#</a></h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 434     No support for signing.  That also means that it is not checked
 435     whether the encryption subkey belongs to the master key.
 436     </p></li><li class="listitem"><p>
 437     No support for encryption key as master key.  As such practice
 438     is generally discouraged, this should not be a problem.
 439     </p></li><li class="listitem"><p>
 440     No support for several subkeys.  This may seem like a problem, as this
 441     is common practice.  On the other hand, you should not use your regular
 442     GPG/PGP keys with <code class="filename">pgcrypto</code>, but create new ones,
 443     as the usage scenario is rather different.
 444     </p></li></ul></div></div></div><div class="sect2" id="PGCRYPTO-RAW-ENC-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.26.4. Raw Encryption Functions <a href="#PGCRYPTO-RAW-ENC-FUNCS" class="id_link">#</a></h3></div></div></div><p>
 445    These functions only run a cipher over data; they don't have any advanced
 446    features of PGP encryption.  Therefore they have some major problems:
 447   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
 448     They use user key directly as cipher key.
 449     </p></li><li class="listitem"><p>
 450     They don't provide any integrity checking, to see
 451     if the encrypted data was modified.
 452     </p></li><li class="listitem"><p>
 453     They expect that users manage all encryption parameters
 454     themselves, even IV.
 455     </p></li><li class="listitem"><p>
 456     They don't handle text.
 457     </p></li></ol></div><p>
 458    So, with the introduction of PGP encryption, usage of raw
 459    encryption functions is discouraged.
 460   </p><a id="id-1.11.7.36.10.5" class="indexterm"></a><a id="id-1.11.7.36.10.6" class="indexterm"></a><a id="id-1.11.7.36.10.7" class="indexterm"></a><a id="id-1.11.7.36.10.8" class="indexterm"></a><pre class="synopsis">
 461 encrypt(data bytea, key bytea, type text) returns bytea
 462 decrypt(data bytea, key bytea, type text) returns bytea
 463
 464 encrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
 465 decrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
 466 </pre><p>
 467    Encrypt/decrypt data using the cipher method specified by
 468    <em class="parameter"><code>type</code></em>.  The syntax of the
 469    <em class="parameter"><code>type</code></em> string is:
 470
 471 </p><pre class="synopsis">
 472 <em class="replaceable"><code>algorithm</code></em> [<span class="optional"> <code class="literal">-</code> <em class="replaceable"><code>mode</code></em> </span>] [<span class="optional"> <code class="literal">/pad:</code> <em class="replaceable"><code>padding</code></em> </span>]
 473 </pre><p>
 474    where <em class="replaceable"><code>algorithm</code></em> is one of:
 475
 476   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">bf</code> — Blowfish</p></li><li class="listitem"><p><code class="literal">aes</code> — AES (Rijndael-128, -192 or -256)</p></li></ul></div><p>
 477    and <em class="replaceable"><code>mode</code></em> is one of:
 478   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 479     <code class="literal">cbc</code> — next block depends on previous (default)
 480     </p></li><li class="listitem"><p>
 481     <code class="literal">cfb</code> — next block depends on previous encrypted block
 482     </p></li><li class="listitem"><p>
 483     <code class="literal">ecb</code> — each block is encrypted separately (for
 484     testing only)
 485     </p></li></ul></div><p>
 486    and <em class="replaceable"><code>padding</code></em> is one of:
 487   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 488     <code class="literal">pkcs</code> — data may be any length (default)
 489     </p></li><li class="listitem"><p>
 490     <code class="literal">none</code> — data must be multiple of cipher block size
 491     </p></li></ul></div><p>
 492   </p><p>
 493    So, for example, these are equivalent:
 494 </p><pre class="programlisting">
 495 encrypt(data, 'fooz', 'bf')
 496 encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
 497 </pre><p>
 498   </p><p>
 499    In <code class="function">encrypt_iv</code> and <code class="function">decrypt_iv</code>, the
 500    <em class="parameter"><code>iv</code></em> parameter is the initial value for the CBC and
 501    CFB mode;
 502    it is ignored for ECB.
 503    It is clipped or padded with zeroes if not exactly block size.
 504    It defaults to all zeroes in the functions without this parameter.
 505   </p></div><div class="sect2" id="PGCRYPTO-RANDOM-DATA-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.26.5. Random-Data Functions <a href="#PGCRYPTO-RANDOM-DATA-FUNCS" class="id_link">#</a></h3></div></div></div><a id="id-1.11.7.36.11.2" class="indexterm"></a><pre class="synopsis">
 506 gen_random_bytes(count integer) returns bytea
 507 </pre><p>
 508    Returns <em class="parameter"><code>count</code></em> cryptographically strong random bytes.
 509    At most 1024 bytes can be extracted at a time.  This is to avoid
 510    draining the randomness generator pool.
 511   </p><a id="id-1.11.7.36.11.5" class="indexterm"></a><pre class="synopsis">
 512 gen_random_uuid() returns uuid
 513 </pre><p>
 514    Returns a version 4 (random) UUID. (Obsolete, this function
 515    internally calls the <a class="link" href="functions-uuid.html" title="9.14. UUID Functions">core
 516    function</a> of the same name.)
 517   </p></div><div class="sect2" id="PGCRYPTO-OPENSSL-SUPPORT-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.26.6. OpenSSL Support Functions <a href="#PGCRYPTO-OPENSSL-SUPPORT-FUNCS" class="id_link">#</a></h3></div></div></div><a id="id-1.11.7.36.12.2" class="indexterm"></a><pre class="synopsis">
 518 fips_mode() returns boolean
 519 </pre><p>
 520    Returns <code class="literal">true</code> if <span class="productname">OpenSSL</span> is
 521    running with FIPS mode enabled, otherwise <code class="literal">false</code>.
 522   </p></div><div class="sect2" id="PGCRYPTO-CONFIGURATION-PARAMETERS"><div class="titlepage"><div><div><h3 class="title">F.26.7. Configuration Parameters <a href="#PGCRYPTO-CONFIGURATION-PARAMETERS" class="id_link">#</a></h3></div></div></div><p>
 523   There is one configuration parameter that controls the behavior of
 524   <code class="filename">pgcrypto</code>.
 525  </p><div class="variablelist"><dl class="variablelist"><dt id="PGCRYPTO-CONFIGURATION-PARAMETERS-BUILTIN_CRYPTO_ENABLED"><span class="term">
 526      <code class="varname">pgcrypto.builtin_crypto_enabled</code> (<code class="type">enum</code>)
 527      <a id="id-1.11.7.36.13.3.1.1.3" class="indexterm"></a>
 528     </span> <a href="#PGCRYPTO-CONFIGURATION-PARAMETERS-BUILTIN_CRYPTO_ENABLED" class="id_link">#</a></dt><dd><p>
 529       <code class="varname">pgcrypto.builtin_crypto_enabled</code> determines if the
 530       built in crypto functions <code class="function">gen_salt()</code>, and
 531       <code class="function">crypt()</code> are available for use. Setting this to
 532       <code class="literal">off</code> disables these functions. <code class="literal">on</code>
 533       (the default) enables these functions to work normally.
 534       <code class="literal">fips</code> disables these functions if
 535       <span class="productname">OpenSSL</span> is detected to operate in FIPS mode.
 536      </p></dd></dl></div><p>
 537    In ordinary usage, this parameter is set
 538    in <code class="filename">postgresql.conf</code>, although superusers can alter it
 539    on-the-fly within their own sessions.
 540   </p></div><div class="sect2" id="PGCRYPTO-NOTES"><div class="titlepage"><div><div><h3 class="title">F.26.8. Notes <a href="#PGCRYPTO-NOTES" class="id_link">#</a></h3></div></div></div><div class="sect3" id="PGCRYPTO-NOTES-CONFIG"><div class="titlepage"><div><div><h4 class="title">F.26.8.1. Configuration <a href="#PGCRYPTO-NOTES-CONFIG" class="id_link">#</a></h4></div></div></div><p>
 541     <code class="filename">pgcrypto</code> configures itself according to the findings of the
 542     main PostgreSQL <code class="literal">configure</code> script.  The options that
 543     affect it are <code class="literal">--with-zlib</code> and
 544     <code class="literal">--with-ssl=openssl</code>.
 545    </p><p>
 546     When compiled with zlib, PGP encryption functions are able to
 547     compress data before encrypting.
 548    </p><p>
 549     <code class="filename">pgcrypto</code> requires <span class="productname">OpenSSL</span>.
 550     Otherwise, it will not be built or installed.
 551    </p><p>
 552     When compiled against <span class="productname">OpenSSL</span> 3.0.0 and later
 553     versions, the legacy provider must be activated in the
 554     <code class="filename">openssl.cnf</code> configuration file in order to use older
 555     ciphers like DES or Blowfish.
 556    </p></div><div class="sect3" id="PGCRYPTO-NOTES-NULL-HANDLING"><div class="titlepage"><div><div><h4 class="title">F.26.8.2. NULL Handling <a href="#PGCRYPTO-NOTES-NULL-HANDLING" class="id_link">#</a></h4></div></div></div><p>
 557     As is standard in SQL, all functions return NULL, if any of the arguments
 558     are NULL.  This may create security risks on careless usage.
 559    </p></div><div class="sect3" id="PGCRYPTO-NOTES-SEC-LIMITS"><div class="titlepage"><div><div><h4 class="title">F.26.8.3. Security Limitations <a href="#PGCRYPTO-NOTES-SEC-LIMITS" class="id_link">#</a></h4></div></div></div><p>
 560     All <code class="filename">pgcrypto</code> functions run inside the database server.
 561     That means that all
 562     the data and passwords move between <code class="filename">pgcrypto</code> and client
 563     applications in clear text.  Thus you must:
 564    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Connect locally or use SSL connections.</p></li><li class="listitem"><p>Trust both system and database administrator.</p></li></ol></div><p>
 565     If you cannot, then better do crypto inside client application.
 566    </p><p>
 567     The implementation does not resist
 568     <a class="ulink" href="https://en.wikipedia.org/wiki/Side-channel_attack" target="_top">side-channel
 569     attacks</a>.  For example, the time required for
 570     a <code class="filename">pgcrypto</code> decryption function to complete varies among
 571     ciphertexts of a given size.
 572    </p></div></div><div class="sect2" id="PGCRYPTO-AUTHOR"><div class="titlepage"><div><div><h3 class="title">F.26.9. Author <a href="#PGCRYPTO-AUTHOR" class="id_link">#</a></h3></div></div></div><p>
 573    Marko Kreen <code class="email">&lt;<a class="email" href="mailto:markokr@gmail.com">markokr@gmail.com</a>&gt;</code>
 574   </p><p>
 575    <code class="filename">pgcrypto</code> uses code from the following sources:
 576   </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Algorithm</th><th>Author</th><th>Source origin</th></tr></thead><tbody><tr><td>DES crypt</td><td>David Burren and others</td><td>FreeBSD libcrypt</td></tr><tr><td>MD5 crypt</td><td>Poul-Henning Kamp</td><td>FreeBSD libcrypt</td></tr><tr><td>Blowfish crypt</td><td>Solar Designer</td><td>www.openwall.com</td></tr></tbody></table></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgbuffercache.html" title="F.25. pg_buffercache — inspect PostgreSQL&#10;    buffer cache state">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgfreespacemap.html" title="F.27. pg_freespacemap — examine the free space map">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.25. pg_buffercache — inspect <span class="productname">PostgreSQL</span>
 577     buffer cache state </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.27. pg_freespacemap — examine the free space map</td></tr></table></div></body></html>