<!-- doc/src/sgml/pgcrypto.sgml -->

<sect1 id="pgcrypto" xreflabel="pgcrypto">
 <title>pgcrypto &mdash; cryptographic functions</title>

 <indexterm zone="pgcrypto">
  <primary>pgcrypto</primary>
 </indexterm>

 <indexterm zone="pgcrypto">
  <primary>encryption</primary>
  <secondary>for specific columns</secondary>
 </indexterm>

 <para>
  The <filename>pgcrypto</filename> module provides cryptographic functions for
  <productname>PostgreSQL</productname>.
 </para>

 <para>
  This module is considered <quote>trusted</quote>, that is, it can be
  installed by non-superusers who have <literal>CREATE</literal> privilege
  on the current database.
 </para>

 <para>
  <filename>pgcrypto</filename> requires OpenSSL and won't be installed if
  OpenSSL support was not selected when PostgreSQL was built.
 </para>

 <sect2 id="pgcrypto-general-hashing-funcs">
  <title>General Hashing Functions</title>

  <sect3 id="pgcrypto-general-hashing-funcs-digest">
   <title><function>digest()</function></title>

   <indexterm>
    <primary>digest</primary>
   </indexterm>

<synopsis>
digest(data text, type text) returns bytea
digest(data bytea, type text) returns bytea
</synopsis>

   <para>
    Computes a binary hash of the given <parameter>data</parameter>.
    <parameter>type</parameter> is the algorithm to use.
    Standard algorithms are <literal>md5</literal>, <literal>sha1</literal>,
    <literal>sha224</literal>, <literal>sha256</literal>,
    <literal>sha384</literal> and <literal>sha512</literal>.
    Moreover, any digest algorithm <productname>OpenSSL</productname> supports
    is automatically picked up.
   </para>

   <para>
    If you want the digest as a hexadecimal string, use
    <function>encode()</function> on the result.  For example:
<programlisting>
CREATE OR REPLACE FUNCTION sha1(bytea) returns text AS $$
    SELECT encode(digest($1, 'sha1'), 'hex')
$$ LANGUAGE SQL STRICT IMMUTABLE;
</programlisting>
   </para>
  </sect3>

  <sect3 id="pgcrypto-general-hashing-funcs-hmac">
   <title><function>hmac()</function></title>

   <indexterm>
    <primary>hmac</primary>
   </indexterm>

<synopsis>
hmac(data text, key text, type text) returns bytea
hmac(data bytea, key bytea, type text) returns bytea
</synopsis>

   <para>
    Calculates hashed MAC for <parameter>data</parameter> with key <parameter>key</parameter>.
    <parameter>type</parameter> is the same as in <function>digest()</function>.
   </para>

   <para>
    This is similar to <function>digest()</function> but the hash can only be
    recalculated knowing the key.  This prevents the scenario of someone
    altering data and also changing the hash to match.
   </para>

   <para>
    If the key is larger than the hash block size it will first be hashed and
    the result will be used as key.
   </para>
  </sect3>
 </sect2>

 <sect2 id="pgcrypto-password-hashing-funcs">
  <title>Password Hashing Functions</title>

  <para>
   The functions <function>crypt()</function> and <function>gen_salt()</function>
   are specifically designed for hashing passwords.
   <function>crypt()</function> does the hashing and <function>gen_salt()</function>
   prepares algorithm parameters for it.
  </para>

  <para>
   The algorithms in <function>crypt()</function> differ from the usual
   MD5 or SHA-1 hashing algorithms in the following respects:
  </para>

  <orderedlist>
   <listitem>
    <para>
     They are slow.  As the amount of data is so small, this is the only
     way to make brute-forcing passwords hard.
    </para>
   </listitem>
   <listitem>
    <para>
     They use a random value, called the <firstterm>salt</firstterm>, so that users
     having the same password will have different encrypted passwords.
     This is also an additional defense against reversing the algorithm.
    </para>
   </listitem>
   <listitem>
    <para>
     They include the algorithm type in the result, so passwords hashed with
     different algorithms can co-exist.
    </para>
   </listitem>
   <listitem>