head	1.13;
access;
symbols
	REL9_0_0:1.9.2.4
	REL9_1_ALPHA1:1.13
	REL9_0_RC1:1.9.2.4
	REL9_0_BETA4:1.9.2.1
	REL9_0_STABLE:1.9.0.2
	REL9_0_BETA3:1.9
	REL9_0_BETA2:1.8
	REL8_3_11:1.6
	REL8_4_4:1.7.2.1
	REL9_0_BETA1:1.8
	REL9_0_ALPHA5_BRANCH:1.8.0.6
	REL9_0_ALPHA5:1.8
	REL8_3_10:1.6
	REL8_4_3:1.7.2.1
	REL9_0_ALPHA4:1.8
	REL9_0_ALPHA4_BRANCH:1.8.0.4
	REL8_5_ALPHA3:1.8
	REL8_5_ALPHA3_BRANCH:1.8.0.2
	REL8_3_9:1.6
	REL8_4_2:1.7.2.1
	REL8_5_ALPHA2:1.7
	REL8_5_ALPHA2_BRANCH:1.7.0.6
	REL8_3_8:1.6
	REL8_4_1:1.7
	REL8_5_ALPHA1:1.7
	REL8_5_ALPHA1_BRANCH:1.7.0.4
	REL8_4_STABLE:1.7.0.2
	REL8_4_0:1.7
	REL8_4_RC2:1.7
	REL8_4_RC1:1.7
	REL8_4_BETA2:1.6
	REL8_4_BETA1:1.6
	REL8_3_7:1.6
	REL8_3_6:1.6
	REL8_3_5:1.6
	REL8_3_4:1.6
	REL8_3_3:1.6
	REL8_3_2:1.6
	REL8_3_1:1.6
	REL8_3_STABLE:1.6.0.2
	REL8_3_0:1.6
	REL8_3_RC2:1.6
	REL8_3_RC1:1.3
	REL8_3_BETA4:1.2
	REL8_3_BETA3:1.2;
locks; strict;
comment	@# @;


1.13
date	2010.08.17.04.37.21;	author petere;	state Exp;
branches;
next	1.12;

1.12
date	2010.08.15.01.57.03;	author rhaas;	state Exp;
branches;
next	1.11;

1.11
date	2010.08.10.20.42.01;	author petere;	state Exp;
branches;
next	1.10;

1.10
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.9;

1.9
date	2010.06.29.22.29.14;	author momjian;	state Exp;
branches
	1.9.2.1;
next	1.8;

1.8
date	2009.12.08.20.08.30;	author mha;	state Exp;
branches;
next	1.7;

1.7
date	2009.05.18.11.08.24;	author petere;	state Exp;
branches
	1.7.2.1;
next	1.6;

1.6
date	2008.01.17.14.34.45;	author mha;	state Exp;
branches;
next	1.5;

1.5
date	2008.01.17.11.06.28;	author mha;	state Exp;
branches;
next	1.4;

1.4
date	2008.01.05.13.17.00;	author petere;	state Exp;
branches;
next	1.3;

1.3
date	2007.12.16.23.00.42;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2007.11.11.14.23.18;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	2007.11.10.23.30.46;	author momjian;	state Exp;
branches;
next	;

1.7.2.1
date	2009.12.08.20.08.37;	author mha;	state Exp;
branches;
next	1.7.2.2;

1.7.2.2
date	2010.08.15.01.57.21;	author rhaas;	state Exp;
branches;
next	;

1.9.2.1
date	2010.07.29.19.34.37;	author petere;	state Exp;
branches;
next	1.9.2.2;

1.9.2.2
date	2010.08.10.20.42.02;	author petere;	state Exp;
branches;
next	1.9.2.3;

1.9.2.3
date	2010.08.15.01.57.12;	author rhaas;	state Exp;
branches;
next	1.9.2.4;

1.9.2.4
date	2010.08.17.04.37.17;	author petere;	state Exp;
branches;
next	;


desc
@@


1.13
log
@Spell and markup checking
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.12 2010/08/15 01:57:03 rhaas Exp $ -->

<sect1 id="pgcrypto">
 <title>pgcrypto</title>

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

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

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

 <sect2>
  <title>General hashing functions</title>

  <sect3>
   <title><function>digest()</function></title>

<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>type</> 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>.
    If <filename>pgcrypto</> was built with
    OpenSSL, more algorithms are available, as detailed in
    <xref linkend="pgcrypto-with-without-openssl">.
   </para>

   <para>
    If you want the digest as a hexadecimal string, use
    <function>encode()</> 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>
   <title><function>hmac()</function></title>

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

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

   <para>
    This is similar to <function>digest()</> 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>
  <title>Password hashing functions</title>

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

  <para>
   The algorithms in <function>crypt()</> differ from usual hashing algorithms
   like MD5 or SHA1 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</>, 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>
    <para>
     Some of them are adaptive &mdash; that means when computers get
     faster, you can tune the algorithm to be slower, without
     introducing incompatibility with existing passwords.
    </para>
   </listitem>
  </orderedlist>

  <para>
   <xref linkend="pgcrypto-crypt-algorithms"> lists the algorithms
   supported by the <function>crypt()</function> function.
  </para>

  <table id="pgcrypto-crypt-algorithms">
   <title>Supported algorithms for <function>crypt()</></title>
   <tgroup cols="5">
    <thead>
     <row>
      <entry>Algorithm</entry>
      <entry>Max password length</entry>
      <entry>Adaptive?</entry>
      <entry>Salt bits</entry>
      <entry>Description</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><literal>bf</></entry>
      <entry>72</entry>
      <entry>yes</entry>
      <entry>128</entry>
      <entry>Blowfish-based, variant 2a</entry>
     </row>
     <row>
      <entry><literal>md5</></entry>
      <entry>unlimited</entry>
      <entry>no</entry>
      <entry>48</entry>
      <entry>MD5-based crypt</entry>
     </row>
     <row>
      <entry><literal>xdes</></entry>
      <entry>8</entry>
      <entry>yes</entry>
      <entry>24</entry>
      <entry>Extended DES</entry>
     </row>
     <row>
      <entry><literal>des</></entry>
      <entry>8</entry>
      <entry>no</entry>
      <entry>12</entry>
      <entry>Original UNIX crypt</entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <sect3>
   <title><function>crypt()</></title>

<synopsis>
crypt(password text, salt text) returns text
</synopsis>

   <para>
    Calculates a crypt(3)-style hash of <parameter>password</>.
    When storing a new password, you need to use
    <function>gen_salt()</> to generate a new <parameter>salt</> value.
    To check a password, pass the stored hash value as <parameter>salt</>,
    and test whether the result matches the stored value.
   </para>
   <para>
    Example of setting a new password:
<programlisting>
UPDATE ... SET pswhash = crypt('new password', gen_salt('md5'));
</programlisting>
   </para>
   <para>
    Example of authentication:
<programlisting>
SELECT pswhash = crypt('entered password', pswhash) FROM ... ;
</programlisting>
    This returns <literal>true</> if the entered password is correct.
   </para>
  </sect3>

  <sect3>
   <title><function>gen_salt()</></title>

<synopsis>
gen_salt(type text [, iter_count integer ]) returns text
</synopsis>

   <para>
    Generates a new random salt string for use in <function>crypt()</>.
    The salt string also tells <function>crypt()</> which algorithm to use.
   </para>

   <para>
    The <parameter>type</> parameter specifies the hashing algorithm.
    The accepted types are: <literal>des</literal>, <literal>xdes</literal>,
    <literal>md5</literal> and <literal>bf</literal>.
   </para>

   <para>
    The <parameter>iter_count</> parameter lets the user specify the iteration
    count, for algorithms that have one.
    The higher the count, the more time it takes to hash
    the password and therefore the more time to break it.  Although with
    too high a count the time to calculate a hash may be several years
    &mdash; which is somewhat impractical.  If the <parameter>iter_count</>
    parameter is omitted, the default iteration count is used.
    Allowed values for <parameter>iter_count</> depend on the algorithm and
    are shown in <xref linkend="pgcrypto-icfc-table">.
   </para>

   <table id="pgcrypto-icfc-table">
    <title>Iteration counts for <function>crypt()</></title>
    <tgroup cols="4">
     <thead>
      <row>
       <entry>Algorithm</entry>
       <entry>Default</entry>
       <entry>Min</entry>
       <entry>Max</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>xdes</></entry>
       <entry>725</entry>
       <entry>1</entry>
       <entry>16777215</entry>
      </row>
      <row>
       <entry><literal>bf</></entry>
       <entry>6</entry>
       <entry>4</entry>
       <entry>31</entry>
      </row>
     </tbody>
    </tgroup>
   </table>

   <para>
    For <literal>xdes</literal> there is an additional limitation that the
    iteration count must be an odd number.
   </para>

   <para>
    To pick an appropriate iteration count, consider that
    the original DES crypt was designed to have the speed of 4 hashes per
    second on the hardware of that time.
    Slower than 4 hashes per second would probably dampen usability.
    Faster than 100 hashes per second is probably too fast.
   </para>

   <para>
    <xref linkend="pgcrypto-hash-speed-table"> gives an overview of the relative slowness
    of different hashing algorithms.
    The table shows how much time it would take to try all
    combinations of characters in an 8-character password, assuming
    that the password contains either only lower case letters, or
    upper- and lower-case letters and numbers.
    In the <literal>crypt-bf</literal> entries, the number after a slash is
    the <parameter>iter_count</parameter> parameter of
    <function>gen_salt</function>.
   </para>

   <table id="pgcrypto-hash-speed-table">
    <title>Hash algorithm speeds</title>
    <tgroup cols="4">
     <thead>
      <row>
       <entry>Algorithm</entry>
       <entry>Hashes/sec</entry>
       <entry>For <literal>[a-z]</></entry>
       <entry>For <literal>[A-Za-z0-9]</></entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>crypt-bf/8</></entry>
       <entry>28</entry>
       <entry>246 years</entry>
       <entry>251322 years</entry>
      </row>
      <row>
       <entry><literal>crypt-bf/7</></entry>
       <entry>57</entry>
       <entry>121 years</entry>
       <entry>123457 years</entry>
      </row>
      <row>
       <entry><literal>crypt-bf/6</></entry>
       <entry>112</entry>
       <entry>62 years</entry>
       <entry>62831 years</entry>
      </row>
      <row>
       <entry><literal>crypt-bf/5</></entry>
       <entry>211</entry>
       <entry>33 years</entry>
       <entry>33351 years</entry>
      </row>
      <row>
       <entry><literal>crypt-md5</></entry>
       <entry>2681</entry>
       <entry>2.6 years</entry>
       <entry>2625 years</entry>
      </row>
      <row>
       <entry><literal>crypt-des</></entry>
       <entry>362837</entry>
       <entry>7 days</entry>
       <entry>19 years</entry>
      </row>
      <row>
       <entry><literal>sha1</></entry>
       <entry>590223</entry>
       <entry>4 days</entry>
       <entry>12 years</entry>
      </row>
      <row>
       <entry><literal>md5</></entry>
       <entry>2345086</entry>
       <entry>1 day</entry>
       <entry>3 years</entry>
      </row>
     </tbody>
    </tgroup>
   </table>

   <para>
    Notes:
   </para>

   <itemizedlist>
    <listitem>
     <para>
     The machine used is a 1.5GHz Pentium 4.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>crypt-des</> and <literal>crypt-md5</> algorithm numbers are
      taken from John the Ripper v1.6.38 <literal>-test</> output.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>md5</> numbers are from mdcrack 1.2.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>sha1</> numbers are from lcrack-20031130-beta.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>crypt-bf</literal> numbers are taken using a simple program that
      loops over 1000 8-character passwords.  That way I can show the speed
      with different numbers of iterations.  For reference: <literal>john
      -test</literal> shows 213 loops/sec for <literal>crypt-bf/5</>.
      (The very small
      difference in results is in accordance with the fact that the
      <literal>crypt-bf</literal> implementation in <filename>pgcrypto</>
      is the same one used in John the Ripper.)
     </para>
    </listitem>
   </itemizedlist>

   <para>
    Note that <quote>try all combinations</quote> is not a realistic exercise.
    Usually password cracking is done with the help of dictionaries, which
    contain both regular words and various mutations of them.  So, even
    somewhat word-like passwords could be cracked much faster than the above
    numbers suggest, while a 6-character non-word-like password may escape
    cracking.  Or not.
   </para>
  </sect3>
 </sect2>

 <sect2>
  <title>PGP encryption functions</title>

  <para>
   The functions here implement the encryption part of the OpenPGP (RFC 4880)
   standard.  Supported are both symmetric-key and public-key encryption.
  </para>

  <para>
   An encrypted PGP message consists of 2 parts, or <firstterm>packets</>:
  </para>
  <itemizedlist>
   <listitem>
    <para>
     Packet containing a session key &mdash; either symmetric-key or public-key
     encrypted.
    </para>
   </listitem>
   <listitem>
    <para>
     Packet containing data encrypted with the session key.
    </para>
   </listitem>
  </itemizedlist>

  <para>
   When encrypting with a symmetric key (i.e., a password):
  </para>
  <orderedlist>
   <listitem>
    <para>
     The given password is hashed using a String2Key (S2K) algorithm.  This is
     rather similar to <function>crypt()</> algorithms &mdash; purposefully
     slow and with random salt &mdash; but it produces a full-length binary
     key.
    </para>
   </listitem>
   <listitem>
    <para>
     If a separate session key is requested, a new random key will be
     generated.  Otherwise the S2K key will be used directly as the session
     key.
    </para>
   </listitem>
   <listitem>
    <para>
     If the S2K key is to be used directly, then only S2K settings will be put
     into the session key packet.  Otherwise the session key will be encrypted
     with the S2K key and put into the session key packet.
    </para>
   </listitem>
  </orderedlist>

  <para>
   When encrypting with a public key:
  </para>
  <orderedlist>
   <listitem>
    <para>
     A new random session key is generated.
    </para>
   </listitem>
   <listitem>
    <para>
     It is encrypted using the public key and put into the session key packet.
    </para>
   </listitem>
  </orderedlist>

  <para>
   In either case the data to be encrypted is processed as follows:
  </para>
  <orderedlist>
   <listitem>
    <para>
     Optional data-manipulation: compression, conversion to UTF-8,
     and/or conversion of line-endings.
    </para>
   </listitem>
   <listitem>
    <para>
     The data is prefixed with a block of random bytes.  This is equivalent
     to using a random IV.
    </para>
   </listitem>
   <listitem>
    <para>
     An SHA1 hash of the random prefix and data is appended.
    </para>
   </listitem>
   <listitem>
    <para>
     All this is encrypted with the session key and placed in the data packet.
    </para>
   </listitem>
  </orderedlist>

  <sect3>
   <title><function>pgp_sym_encrypt()</function></title>

<synopsis>
pgp_sym_encrypt(data text, psw text [, options text ]) returns bytea
pgp_sym_encrypt_bytea(data bytea, psw text [, options text ]) returns bytea
</synopsis>
   <para>
    Encrypt <parameter>data</> with a symmetric PGP key <parameter>psw</>.
    The <parameter>options</> parameter can contain option settings,
    as described below.
   </para>
  </sect3>

  <sect3>
   <title><function>pgp_sym_decrypt()</function></title>

<synopsis>
pgp_sym_decrypt(msg bytea, psw text [, options text ]) returns text
pgp_sym_decrypt_bytea(msg bytea, psw text [, options text ]) returns bytea
</synopsis>
   <para>
    Decrypt a symmetric-key-encrypted PGP message.
   </para>
   <para>
    Decrypting <type>bytea</> data with <function>pgp_sym_decrypt</> is disallowed.
    This is to avoid outputting invalid character data.  Decrypting
    originally textual data with <function>pgp_sym_decrypt_bytea</> is fine.
   </para>
   <para>
    The <parameter>options</> parameter can contain option settings,
    as described below.
   </para>
  </sect3>

  <sect3>
   <title><function>pgp_pub_encrypt()</function></title>

<synopsis>
pgp_pub_encrypt(data text, key bytea [, options text ]) returns bytea
pgp_pub_encrypt_bytea(data bytea, key bytea [, options text ]) returns bytea
</synopsis>
   <para>
    Encrypt <parameter>data</> with a public PGP key <parameter>key</>.
    Giving this function a secret key will produce a error.
   </para>
   <para>
    The <parameter>options</> parameter can contain option settings,
    as described below.
   </para>
  </sect3>

  <sect3>
   <title><function>pgp_pub_decrypt()</function></title>

<synopsis>
pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text ]]) returns text
pgp_pub_decrypt_bytea(msg bytea, key bytea [, psw text [, options text ]]) returns bytea
</synopsis>
   <para>
    Decrypt a public-key-encrypted message.  <parameter>key</> must be the
    secret key corresponding to the public key that was used to encrypt.
    If the secret key is password-protected, you must give the password in
    <parameter>psw</>.  If there is no password, but you want to specify
    options, you need to give an empty password.
   </para>
   <para>
    Decrypting <type>bytea</> data with <function>pgp_pub_decrypt</> is disallowed.
    This is to avoid outputting invalid character data.  Decrypting
    originally textual data with <function>pgp_pub_decrypt_bytea</> is fine.
   </para>
   <para>
    The <parameter>options</> parameter can contain option settings,
    as described below.
   </para>
  </sect3>

  <sect3>
   <title><function>pgp_key_id()</function></title>

<synopsis>
pgp_key_id(bytea) returns text
</synopsis>
   <para>
    <function>pgp_key_id</> extracts the key ID of a PGP public or secret key.
    Or it gives the key ID that was used for encrypting the data, if given
    an encrypted message.
   </para>
   <para>
    It can return 2 special key IDs:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      <literal>SYMKEY</>
     </para>
     <para>
      The message is encrypted with a symmetric key.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>ANYKEY</>
     </para>
     <para>
      The message is public-key encrypted, but the key ID has been removed.
      That means you will need to try all your secret keys on it to see
      which one decrypts it.  <filename>pgcrypto</> itself does not produce
      such messages.
     </para>
    </listitem>
   </itemizedlist>
   <para>
    Note that different keys may have the same ID.   This is rare but a normal
    event. The client application should then try to decrypt with each one,
    to see which fits &mdash; like handling <literal>ANYKEY</>.
   </para>
  </sect3>

  <sect3>
   <title><function>armor()</function>, <function>dearmor()</function></title>

<synopsis>
armor(data bytea) returns text
dearmor(data text) returns bytea
</synopsis>
   <para>
    These functions wrap/unwrap binary data into PGP ASCII-armor format,
    which is basically Base64 with CRC and additional formatting.
   </para>
  </sect3>

  <sect3>
   <title>Options for PGP functions</title>

   <para>
    Options are named to be similar to GnuPG.  An option's value should be
    given after an equal sign; separate options from each other with commas.
    For example:
<programlisting>
pgp_sym_encrypt(data, psw, 'compress-algo=1, cipher-algo=aes256')
</programlisting>
   </para>

   <para>
    All of the options except <literal>convert-crlf</literal> apply only to
    encrypt functions.  Decrypt functions get the parameters from the PGP
    data.
   </para>

   <para>
    The most interesting options are probably
    <literal>compress-algo</literal> and <literal>unicode-mode</literal>.
    The rest should have reasonable defaults.
   </para>

  <sect4>
   <title>cipher-algo</title>

   <para>
    Which cipher algorithm to use.
   </para>
<literallayout>
Values: bf, aes128, aes192, aes256 (OpenSSL-only: <literal>3des</literal>, <literal>cast5</literal>)
Default: aes128
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
  </sect4>

  <sect4>
   <title>compress-algo</title>

   <para>
    Which compression algorithm to use.  Only available if
    <productname>PostgreSQL</productname> was built with zlib.
   </para>
<literallayout>
Values:
  0 - no compression
  1 - ZIP compression
  2 - ZLIB compression (= ZIP plus meta-data and block CRCs)
Default: 0
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
  </sect4>

  <sect4>
   <title>compress-level</title>

   <para>
    How much to compress.  Higher levels compress smaller but are slower.
    0 disables compression.
   </para>
<literallayout>
Values: 0, 1-9
Default: 6
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
  </sect4>

  <sect4>
   <title>convert-crlf</title>

   <para>
    Whether to convert <literal>\n</literal> into <literal>\r\n</literal> when
    encrypting and <literal>\r\n</literal> to <literal>\n</literal> when
    decrypting.  RFC 4880 specifies that text data should be stored using
    <literal>\r\n</literal> line-feeds.  Use this to get fully RFC-compliant
    behavior.
   </para>
<literallayout>
Values: 0, 1
Default: 0
Applies to: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt
</literallayout>
  </sect4>

  <sect4>
   <title>disable-mdc</title>

   <para>
    Do not protect data with SHA-1.  The only good reason to use this
    option is to achieve compatibility with ancient PGP products, predating
    the addition of SHA-1 protected packets to RFC 4880.
    Recent gnupg.org and pgp.com software supports it fine.
   </para>
<literallayout>
Values: 0, 1
Default: 0
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
  </sect4>

  <sect4>
   <title>enable-session-key</title>

   <para>
    Use separate session key.  Public-key encryption always uses a separate
    session key; this is for symmetric-key encryption, which by default
    uses the S2K key directly.
   </para>
<literallayout>
Values: 0, 1
Default: 0
Applies to: pgp_sym_encrypt
</literallayout>
  </sect4>

  <sect4>
   <title>s2k-mode</title>

   <para>
    Which S2K algorithm to use.
   </para>
<literallayout>
Values:
  0 - Without salt.  Dangerous!
  1 - With salt but with fixed iteration count.
  3 - Variable iteration count.
Default: 3
Applies to: pgp_sym_encrypt
</literallayout>
  </sect4>

  <sect4>
   <title>s2k-digest-algo</title>

   <para>
    Which digest algorithm to use in S2K calculation.
   </para>
<literallayout>
Values: md5, sha1
Default: sha1
Applies to: pgp_sym_encrypt
</literallayout>
  </sect4>

  <sect4>
   <title>s2k-cipher-algo</title>

   <para>
    Which cipher to use for encrypting separate session key.
   </para>
<literallayout>
Values: bf, aes, aes128, aes192, aes256
Default: use cipher-algo
Applies to: pgp_sym_encrypt
</literallayout>
  </sect4>

  <sect4>
   <title>unicode-mode</title>

   <para>
    Whether to convert textual data from database internal encoding to
    UTF-8 and back.  If your database already is UTF-8, no conversion will
    be done, but the message will be tagged as UTF-8.  Without this option
    it will not be.
   </para>
<literallayout>
Values: 0, 1
Default: 0
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
  </sect4>
  </sect3>

 <sect3>
  <title>Generating PGP keys with GnuPG</title>

  <para>
   To generate a new key:
<programlisting>
gpg --gen-key
</programlisting>
  </para>
  <para>
   The preferred key type is <quote>DSA and Elgamal</>.
  </para>
  <para>
   For RSA encryption you must create either DSA or RSA sign-only key
   as master and then add an RSA encryption subkey with
   <literal>gpg --edit-key</literal>.
  </para>
  <para>
   To list keys:
<programlisting>
gpg --list-secret-keys
</programlisting>
  </para>
  <para>
   To export a public key in ASCII-armor format:
<programlisting>
gpg -a --export KEYID > public.key
</programlisting>
  </para>
  <para>
   To export a secret key in ASCII-armor format:
<programlisting>
gpg -a --export-secret-keys KEYID > secret.key
</programlisting>
  </para>
  <para>
   You need to use <function>dearmor()</> on these keys before giving them to
   the PGP functions.  Or if you can handle binary data, you can drop
   <literal>-a</literal> from the command.
  </para>
  <para>
   For more details see <literal>man gpg</literal>,
   <ulink url="http://www.gnupg.org/gph/en/manual.html">The GNU
   Privacy Handbook</ulink> and other documentation on
   <ulink url="http://www.gnupg.org"></ulink>.
  </para>
 </sect3>

 <sect3>
  <title>Limitations of PGP code</title>

  <itemizedlist>
   <listitem>
    <para>
    No support for signing.  That also means that it is not checked
    whether the encryption subkey belongs to the master key.
    </para>
   </listitem>
   <listitem>
    <para>
    No support for encryption key as master key.  As such practice
    is generally discouraged, this should not be a problem.
    </para>
   </listitem>
   <listitem>
    <para>
    No support for several subkeys.  This may seem like a problem, as this
    is common practice.  On the other hand, you should not use your regular
    GPG/PGP keys with <filename>pgcrypto</>, but create new ones,
    as the usage scenario is rather different.
    </para>
   </listitem>
  </itemizedlist>
  </sect3>
 </sect2>

 <sect2>
  <title>Raw encryption functions</title>

  <para>
   These functions only run a cipher over data; they don't have any advanced
   features of PGP encryption.  Therefore they have some major problems:
  </para>
  <orderedlist>
   <listitem>
    <para>
    They use user key directly as cipher key.
    </para>
   </listitem>
   <listitem>
    <para>
    They don't provide any integrity checking, to see
    if the encrypted data was modified.
    </para>
   </listitem>
   <listitem>
    <para>
    They expect that users manage all encryption parameters
    themselves, even IV.
    </para>
   </listitem>
   <listitem>
    <para>
    They don't handle text.
    </para>
   </listitem>
  </orderedlist>
  <para>
   So, with the introduction of PGP encryption, usage of raw
   encryption functions is discouraged.
  </para>

<synopsis>
encrypt(data bytea, key bytea, type text) returns bytea
decrypt(data bytea, key bytea, type text) returns bytea

encrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
decrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
</synopsis>

  <para>
   Encrypt/decrypt data using the cipher method specified by
   <parameter>type</parameter>.  The syntax of the
   <parameter>type</parameter> string is:

<synopsis>
<replaceable>algorithm</> <optional> <literal>-</> <replaceable>mode</> </optional> <optional> <literal>/pad:</> <replaceable>padding</> </optional>
</synopsis>
   where <replaceable>algorithm</> is one of:

  <itemizedlist>
   <listitem><para><literal>bf</literal> &mdash; Blowfish</para></listitem>
   <listitem><para><literal>aes</literal> &mdash; AES (Rijndael-128)</para></listitem>
  </itemizedlist>
   and <replaceable>mode</> is one of:
  <itemizedlist>
   <listitem>
    <para>
    <literal>cbc</literal> &mdash; next block depends on previous (default)
    </para>
   </listitem>
   <listitem>
    <para>
    <literal>ecb</literal> &mdash; each block is encrypted separately (for
    testing only)
    </para>
   </listitem>
  </itemizedlist>
   and <replaceable>padding</> is one of:
  <itemizedlist>
   <listitem>
    <para>
    <literal>pkcs</literal> &mdash; data may be any length (default)
    </para>
   </listitem>
   <listitem>
    <para>
    <literal>none</literal> &mdash; data must be multiple of cipher block size
    </para>
   </listitem>
  </itemizedlist>
  </para>
  <para>
   So, for example, these are equivalent:
<programlisting>
encrypt(data, 'fooz', 'bf')
encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
</programlisting>
  </para>
  <para>
   In <function>encrypt_iv</> and <function>decrypt_iv</>, the
   <parameter>iv</> parameter is the initial value for the CBC mode;
   it is ignored for ECB.
   It is clipped or padded with zeroes if not exactly block size.
   It defaults to all zeroes in the functions without this parameter.
  </para>
 </sect2>

 <sect2>
  <title>Random-data functions</title>

<synopsis>
gen_random_bytes(count integer) returns bytea
</synopsis>
  <para>
   Returns <parameter>count</> cryptographically strong random bytes.
   At most 1024 bytes can be extracted at a time.  This is to avoid
   draining the randomness generator pool.
  </para>
 </sect2>

 <sect2>
  <title>Notes</title>

  <sect3>
   <title>Configuration</title>

   <para>
    <filename>pgcrypto</> configures itself according to the findings of the
    main PostgreSQL <literal>configure</literal> script.  The options that
    affect it are <literal>--with-zlib</literal> and
    <literal>--with-openssl</literal>.
   </para>

   <para>
    When compiled with zlib, PGP encryption functions are able to
    compress data before encrypting.
   </para>

   <para>
    When compiled with OpenSSL, there will be more algorithms available.
    Also public-key encryption functions will be faster as OpenSSL
    has more optimized BIGNUM functions.
   </para>

   <table id="pgcrypto-with-without-openssl">
    <title>Summary of functionality with and without OpenSSL</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Functionality</entry>
       <entry>Built-in</entry>
       <entry>With OpenSSL</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>MD5</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>SHA1</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>SHA224/256/384/512</entry>
       <entry>yes</entry>
       <entry>yes (Note 1)</entry>
      </row>
      <row>
       <entry>Other digest algorithms</entry>
       <entry>no</entry>
       <entry>yes (Note 2)</entry>
      </row>
      <row>
       <entry>Blowfish</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>AES</entry>
       <entry>yes</entry>
       <entry>yes (Note 3)</entry>
      </row>
      <row>
       <entry>DES/3DES/CAST5</entry>
       <entry>no</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>Raw encryption</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>PGP Symmetric encryption</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>PGP Public-Key encryption</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
     </tbody>
    </tgroup>
   </table>

   <para>
    Notes:
   </para>

   <orderedlist>
    <listitem>
     <para>
      SHA2 algorithms were added to OpenSSL in version 0.9.8.  For
      older versions, <filename>pgcrypto</> will use built-in code.
     </para>
    </listitem>
    <listitem>
     <para>
      Any digest algorithm OpenSSL supports is automatically picked up.
      This is not possible with ciphers, which need to be supported
      explicitly.
     </para>
    </listitem>
    <listitem>
     <para>
      AES is included in OpenSSL since version 0.9.7.  For
      older versions, <filename>pgcrypto</> will use built-in code.
     </para>
    </listitem>
   </orderedlist>
  </sect3>

  <sect3>
   <title>NULL handling</title>

   <para>
    As is standard in SQL, all functions return NULL, if any of the arguments
    are NULL.  This may create security risks on careless usage.
   </para>
  </sect3>

  <sect3>
   <title>Security limitations</title>

   <para>
    All <filename>pgcrypto</> functions run inside the database server.
    That means that all
    the data and passwords move between <filename>pgcrypto</> and client
    applications in clear text.  Thus you must:
   </para>

   <orderedlist>
    <listitem>
     <para>Connect locally or use SSL connections.</para>
    </listitem>
    <listitem>
     <para>Trust both system and database administrator.</para>
    </listitem>
   </orderedlist>

   <para>
    If you cannot, then better do crypto inside client application.
   </para>
  </sect3>

  <sect3>
   <title>Useful reading</title>

   <itemizedlist>
    <listitem>
     <para><ulink url="http://www.gnupg.org/gph/en/manual.html"></ulink></para>
     <para>The GNU Privacy Handbook.</para>
    </listitem>
    <listitem>
     <para><ulink url="http://www.openwall.com/crypt/"></ulink></para>
     <para>Describes the crypt-blowfish algorithm.</para>
    </listitem>
    <listitem>
     <para>
      <ulink url="http://www.stack.nl/~galactus/remailers/passphrase-faq.html"></ulink>
     </para>
     <para>How to choose a good password.</para>
    </listitem>
    <listitem>
     <para><ulink url="http://world.std.com/~reinhold/diceware.html"></ulink></para>
     <para>Interesting idea for picking passwords.</para>
    </listitem>
    <listitem>
     <para>
      <ulink url="http://www.interhack.net/people/cmcurtin/snake-oil-faq.html"></ulink>
     </para>
     <para>Describes good and bad cryptography.</para>
    </listitem>
   </itemizedlist>
  </sect3>

  <sect3>
   <title>Technical references</title>

   <itemizedlist>
    <listitem>
     <para><ulink url="http://www.ietf.org/rfc/rfc4880.txt"></ulink></para>
     <para>OpenPGP message format.</para>
    </listitem>
    <listitem>
     <para><ulink url="http://www.ietf.org/rfc/rfc1321.txt"></ulink></para>
     <para>The MD5 Message-Digest Algorithm.</para>
    </listitem>
    <listitem>
     <para><ulink url="http://www.ietf.org/rfc/rfc2104.txt"></ulink></para>
     <para>HMAC: Keyed-Hashing for Message Authentication.</para>
    </listitem>
    <listitem>
     <para>
      <ulink url="http://www.usenix.org/events/usenix99/provos.html"></ulink>
     </para>
     <para>Comparison of crypt-des, crypt-md5 and bcrypt algorithms.</para>
    </listitem>
    <listitem>
     <para><ulink url="http://csrc.nist.gov/cryptval/des.htm"></ulink></para>
     <para>Standards for DES, 3DES and AES.</para>
    </listitem>
    <listitem>
     <para>
      <ulink url="http://en.wikipedia.org/wiki/Fortuna_(PRNG)"></ulink>
     </para>
     <para>Description of Fortuna CSPRNG.</para>
    </listitem>
    <listitem>
     <para><ulink url="http://jlcooke.ca/random/"></ulink></para>
     <para>Jean-Luc Cooke Fortuna-based <filename>/dev/random</> driver for Linux.</para>
    </listitem>
    <listitem>
     <para><ulink url="http://research.cyber.ee/~lipmaa/crypto/"></ulink></para>
     <para>Collection of cryptology pointers.</para>
    </listitem>
   </itemizedlist>
  </sect3>
 </sect2>

 <sect2>
  <title>Author</title>

  <para>
   Marko Kreen <email>markokr@@gmail.com</email>
  </para>

  <para>
   <filename>pgcrypto</filename> uses code from the following sources:
  </para>

  <informaltable>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Algorithm</entry>
      <entry>Author</entry>
      <entry>Source origin</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>DES crypt</entry>
      <entry>David Burren and others</entry>
      <entry>FreeBSD libcrypt</entry>
     </row>
     <row>
      <entry>MD5 crypt</entry>
      <entry>Poul-Henning Kamp</entry>
      <entry>FreeBSD libcrypt</entry>
     </row>
     <row>
      <entry>Blowfish crypt</entry>
      <entry>Solar Designer</entry>
      <entry>www.openwall.com</entry>
     </row>
     <row>
      <entry>Blowfish cipher</entry>
      <entry>Simon Tatham</entry>
      <entry>PuTTY</entry>
     </row>
     <row>
      <entry>Rijndael cipher</entry>
      <entry>Brian Gladman</entry>
      <entry>OpenBSD sys/crypto</entry>
     </row>
     <row>
      <entry>MD5 and SHA1</entry>
      <entry>WIDE Project</entry>
      <entry>KAME kame/sys/crypto</entry>
     </row>
     <row>
      <entry>SHA256/384/512 </entry>
      <entry>Aaron D. Gifford</entry>
      <entry>OpenBSD sys/crypto</entry>
     </row>
     <row>
      <entry>BIGNUM math</entry>
      <entry>Michael J. Fromberger</entry>
      <entry>dartmouth.edu/~sting/sw/imath</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </sect2>

</sect1>
@


1.12
log
@Add link and additional index reference to pgcrypto.

Kevin Grittner, with markup adjustments.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.11 2010/08/10 20:42:01 petere Exp $ -->
d522 1
a522 1
    Decrypting bytea data with <function>pgp_sym_decrypt</> is disallowed.
d564 1
a564 1
    Decrypting bytea data with <function>pgp_pub_decrypt</> is disallowed.
d624 1
a624 1
    These functions wrap/unwrap binary data into PGP Ascii Armor format,
d828 1
a828 1
   To export a public key in ascii-armor format:
d834 1
a834 1
   To export a secret key in ascii-armor format:
d1209 1
a1209 1
     <para>Jean-Luc Cooke Fortuna-based /dev/random driver for Linux.</para>
@


1.11
log
@Add some links to tables
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.10 2010/07/29 19:34:40 petere Exp $ -->
d10 5
@


1.10
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.9 2010/06/29 22:29:14 momjian Exp $ -->
d118 6
a123 1
  <table>
@


1.9
log
@In documentation, use "lower case"/"upper case" consistently (use space
between words).
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.8 2009/12/08 20:08:30 mha Exp $ -->
d21 4
a24 4
   <synopsis>
    digest(data text, type text) returns bytea
    digest(data bytea, type text) returns bytea
   </synopsis>
d40 5
a45 5
   <programlisting>
    CREATE OR REPLACE FUNCTION sha1(bytea) returns text AS $$
      SELECT encode(digest($1, 'sha1'), 'hex')
    $$ LANGUAGE SQL STRICT IMMUTABLE;
   </programlisting>
d51 4
a54 4
   <synopsis>
    hmac(data text, key text, type text) returns bytea
    hmac(data bytea, key text, type text) returns bytea
   </synopsis>
d166 3
a168 3
   <synopsis>
    crypt(password text, salt text) returns text
   </synopsis>
d179 3
a182 3
   <programlisting>
    UPDATE ... SET pswhash = crypt('new password', gen_salt('md5'));
   </programlisting>
d185 3
a187 5
   </para>
   <programlisting>
    SELECT pswhash = crypt('entered password', pswhash) FROM ... ;
   </programlisting>
   <para>
d195 3
a197 3
   <synopsis>
    gen_salt(type text [, iter_count integer ]) returns text
   </synopsis>
d490 4
a493 4
   <synopsis>
    pgp_sym_encrypt(data text, psw text [, options text ]) returns bytea
    pgp_sym_encrypt_bytea(data bytea, psw text [, options text ]) returns bytea
   </synopsis>
d504 4
a507 4
   <synopsis>
    pgp_sym_decrypt(msg bytea, psw text [, options text ]) returns text
    pgp_sym_decrypt_bytea(msg bytea, psw text [, options text ]) returns bytea
   </synopsis>
d525 4
a528 4
   <synopsis>
    pgp_pub_encrypt(data text, key bytea [, options text ]) returns bytea
    pgp_pub_encrypt_bytea(data bytea, key bytea [, options text ]) returns bytea
   </synopsis>
d542 4
a545 4
   <synopsis>
    pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text ]]) returns text
    pgp_pub_decrypt_bytea(msg bytea, key bytea [, psw text [, options text ]]) returns bytea
   </synopsis>
d567 3
a569 3
   <synopsis>
    pgp_key_id(bytea) returns text
   </synopsis>
d609 4
a612 4
   <synopsis>
    armor(data bytea) returns text
    dearmor(data text) returns bytea
   </synopsis>
d626 3
a629 3
   <programlisting>
    pgp_sym_encrypt(data, psw, 'compress-algo=1, cipher-algo=aes256')
   </programlisting>
d649 5
a653 5
   <programlisting>
    Values: bf, aes128, aes192, aes256 (OpenSSL-only: <literal>3des</literal>, <literal>cast5</literal>)
    Default: aes128
    Applies to: pgp_sym_encrypt, pgp_pub_encrypt
   </programlisting>
d663 8
a670 8
   <programlisting>
    Values:
      0 - no compression
      1 - ZIP compression
      2 - ZLIB compression (= ZIP plus meta-data and block CRCs)
    Default: 0
    Applies to: pgp_sym_encrypt, pgp_pub_encrypt
   </programlisting>
d680 5
a684 5
   <programlisting>
    Values: 0, 1-9
    Default: 6
    Applies to: pgp_sym_encrypt, pgp_pub_encrypt
   </programlisting>
d697 5
a701 5
   <programlisting>
    Values: 0, 1
    Default: 0
    Applies to: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt
   </programlisting>
d713 5
a717 5
   <programlisting>
    Values: 0, 1
    Default: 0
    Applies to: pgp_sym_encrypt, pgp_pub_encrypt
   </programlisting>
d728 5
a732 5
   <programlisting>
    Values: 0, 1
    Default: 0
    Applies to: pgp_sym_encrypt
   </programlisting>
d741 8
a748 8
   <programlisting>
    Values:
      0 - Without salt.  Dangerous!
      1 - With salt but with fixed iteration count.
      3 - Variable iteration count.
    Default: 3
    Applies to: pgp_sym_encrypt
   </programlisting>
d757 5
a761 5
   <programlisting>
    Values: md5, sha1
    Default: sha1
    Applies to: pgp_sym_encrypt
   </programlisting>
d770 5
a774 5
   <programlisting>
    Values: bf, aes, aes128, aes192, aes256
    Default: use cipher-algo
    Applies to: pgp_sym_encrypt
   </programlisting>
d786 5
a790 5
   <programlisting>
    Values: 0, 1
    Default: 0
    Applies to: pgp_sym_encrypt, pgp_pub_encrypt
   </programlisting>
d799 3
a802 3
  <programlisting>
   gpg --gen-key
  </programlisting>
d813 3
a816 3
  <programlisting>
   gpg --list-secret-keys
  </programlisting>
d819 3
a822 3
  <programlisting>
   gpg -a --export KEYID > public.key
  </programlisting>
d825 3
a828 3
  <programlisting>
   gpg -a --export-secret-keys KEYID > secret.key
  </programlisting>
d906 7
a912 7
  <synopsis>
    encrypt(data bytea, key bytea, type text) returns bytea
    decrypt(data bytea, key bytea, type text) returns bytea

    encrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
    decrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
  </synopsis>
a917 1
  </para>
d919 4
a922 3
  <synopsis>
   <replaceable>algorithm</> <optional> <literal>-</> <replaceable>mode</> </optional> <optional> <literal>/pad:</> <replaceable>padding</> </optional>
  </synopsis>
a923 3
  <para>
   where <replaceable>algorithm</> is one of:
  </para>
a927 1
  <para>
a928 1
  </para>
a941 1
  <para>
a942 1
  </para>
d955 1
d958 4
a962 4
  <programlisting>
   encrypt(data, 'fooz', 'bf')
   encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
  </programlisting>
d975 3
a977 3
  <synopsis>
   gen_random_bytes(count integer) returns bytea
  </synopsis>
@


1.9.2.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.9 2010/06/29 22:29:14 momjian Exp $ -->
d21 4
a24 4
<synopsis>
digest(data text, type text) returns bytea
digest(data bytea, type text) returns bytea
</synopsis>
a39 5
<programlisting>
CREATE OR REPLACE FUNCTION sha1(bytea) returns text AS $$
    SELECT encode(digest($1, 'sha1'), 'hex')
$$ LANGUAGE SQL STRICT IMMUTABLE;
</programlisting>
d41 5
d51 4
a54 4
<synopsis>
hmac(data text, key text, type text) returns bytea
hmac(data bytea, key text, type text) returns bytea
</synopsis>
d166 3
a168 3
<synopsis>
crypt(password text, salt text) returns text
</synopsis>
a178 3
<programlisting>
UPDATE ... SET pswhash = crypt('new password', gen_salt('md5'));
</programlisting>
d180 3
d185 5
a189 3
<programlisting>
SELECT pswhash = crypt('entered password', pswhash) FROM ... ;
</programlisting>
d197 3
a199 3
<synopsis>
gen_salt(type text [, iter_count integer ]) returns text
</synopsis>
d492 4
a495 4
<synopsis>
pgp_sym_encrypt(data text, psw text [, options text ]) returns bytea
pgp_sym_encrypt_bytea(data bytea, psw text [, options text ]) returns bytea
</synopsis>
d506 4
a509 4
<synopsis>
pgp_sym_decrypt(msg bytea, psw text [, options text ]) returns text
pgp_sym_decrypt_bytea(msg bytea, psw text [, options text ]) returns bytea
</synopsis>
d527 4
a530 4
<synopsis>
pgp_pub_encrypt(data text, key bytea [, options text ]) returns bytea
pgp_pub_encrypt_bytea(data bytea, key bytea [, options text ]) returns bytea
</synopsis>
d544 4
a547 4
<synopsis>
pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text ]]) returns text
pgp_pub_decrypt_bytea(msg bytea, key bytea [, psw text [, options text ]]) returns bytea
</synopsis>
d569 3
a571 3
<synopsis>
pgp_key_id(bytea) returns text
</synopsis>
d611 4
a614 4
<synopsis>
armor(data bytea) returns text
dearmor(data text) returns bytea
</synopsis>
a627 3
<programlisting>
pgp_sym_encrypt(data, psw, 'compress-algo=1, cipher-algo=aes256')
</programlisting>
d629 3
d651 5
a655 5
<literallayout>
Values: bf, aes128, aes192, aes256 (OpenSSL-only: <literal>3des</literal>, <literal>cast5</literal>)
Default: aes128
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
d665 8
a672 8
<literallayout>
Values:
  0 - no compression
  1 - ZIP compression
  2 - ZLIB compression (= ZIP plus meta-data and block CRCs)
Default: 0
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
d682 5
a686 5
<literallayout>
Values: 0, 1-9
Default: 6
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
d699 5
a703 5
<literallayout>
Values: 0, 1
Default: 0
Applies to: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt
</literallayout>
d715 5
a719 5
<literallayout>
Values: 0, 1
Default: 0
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
d730 5
a734 5
<literallayout>
Values: 0, 1
Default: 0
Applies to: pgp_sym_encrypt
</literallayout>
d743 8
a750 8
<literallayout>
Values:
  0 - Without salt.  Dangerous!
  1 - With salt but with fixed iteration count.
  3 - Variable iteration count.
Default: 3
Applies to: pgp_sym_encrypt
</literallayout>
d759 5
a763 5
<literallayout>
Values: md5, sha1
Default: sha1
Applies to: pgp_sym_encrypt
</literallayout>
d772 5
a776 5
<literallayout>
Values: bf, aes, aes128, aes192, aes256
Default: use cipher-algo
Applies to: pgp_sym_encrypt
</literallayout>
d788 5
a792 5
<literallayout>
Values: 0, 1
Default: 0
Applies to: pgp_sym_encrypt, pgp_pub_encrypt
</literallayout>
a800 3
<programlisting>
gpg --gen-key
</programlisting>
d802 3
a814 3
<programlisting>
gpg --list-secret-keys
</programlisting>
d816 3
a820 3
<programlisting>
gpg -a --export KEYID > public.key
</programlisting>
d822 3
a826 3
<programlisting>
gpg -a --export-secret-keys KEYID > secret.key
</programlisting>
d828 3
d908 7
a914 7
<synopsis>
encrypt(data bytea, key bytea, type text) returns bytea
decrypt(data bytea, key bytea, type text) returns bytea

encrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
decrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
</synopsis>
d920 1
d922 5
a926 3
<synopsis>
<replaceable>algorithm</> <optional> <literal>-</> <replaceable>mode</> </optional> <optional> <literal>/pad:</> <replaceable>padding</> </optional>
</synopsis>
d928 1
a928 1

d933 1
d935 1
d949 1
d951 1
a963 1
  </para>
a965 4
<programlisting>
encrypt(data, 'fooz', 'bf')
encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
</programlisting>
d967 4
d983 3
a985 3
<synopsis>
gen_random_bytes(count integer) returns bytea
</synopsis>
@


1.9.2.2
log
@Add some links to tables
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.9.2.1 2010/07/29 19:34:37 petere Exp $ -->
d118 1
a118 6
  <para>
   <xref linkend="pgcrypto-crypt-algorithms"> lists the algorithms
   supported by the <function>crypt()</function> function.
  </para>

  <table id="pgcrypto-crypt-algorithms">
@


1.9.2.3
log
@Add link and additional index reference to pgcrypto.

Kevin Grittner, with markup adjustments.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.9.2.2 2010/08/10 20:42:02 petere Exp $ -->
a9 5
 <indexterm zone="pgcrypto">
  <primary>encryption</primary>
  <secondary>for specific columns</secondary>
 </indexterm>

@


1.9.2.4
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.9.2.3 2010/08/15 01:57:12 rhaas Exp $ -->
d522 1
a522 1
    Decrypting <type>bytea</> data with <function>pgp_sym_decrypt</> is disallowed.
d564 1
a564 1
    Decrypting <type>bytea</> data with <function>pgp_pub_decrypt</> is disallowed.
d624 1
a624 1
    These functions wrap/unwrap binary data into PGP ASCII-armor format,
d828 1
a828 1
   To export a public key in ASCII-armor format:
d834 1
a834 1
   To export a secret key in ASCII-armor format:
d1209 1
a1209 1
     <para>Jean-Luc Cooke Fortuna-based <filename>/dev/random</> driver for Linux.</para>
@


1.8
log
@Fix a couple of broken links to third-party sites.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.7 2009/05/18 11:08:24 petere Exp $ -->
d270 1
a270 1
    that the password contains either only lowercase letters, or
@


1.7
log
@Refer to tables by id, not by "the following table", because tables are in
theory floating elements.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.6 2008/01/17 14:34:45 mha Exp $ -->
d1210 1
a1210 1
     <para><ulink url="http://www.cs.ut.ee/~helger/crypto/"></ulink></para>
@


1.7.2.1
log
@Fix a couple of broken links to third-party sites.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.7 2009/05/18 11:08:24 petere Exp $ -->
d1210 1
a1210 1
     <para><ulink url="http://research.cyber.ee/~lipmaa/crypto/"></ulink></para>
@


1.7.2.2
log
@Add link and additional index reference to pgcrypto.

Kevin Grittner, with markup adjustments.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.7.2.1 2009/12/08 20:08:37 mha Exp $ -->
a9 5
 <indexterm zone="pgcrypto">
  <primary>encryption</primary>
  <secondary>for specific columns</secondary>
 </indexterm>

@


1.6
log
@Typo fix.

Erik Rijkers
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.5 2008/01/17 11:06:28 mha Exp $ -->
d220 2
a221 1
    Allowed values for <parameter>iter_count</> depend on the algorithm:
d224 1
a224 1
   <table>
d266 1
a266 1
    Here is a table that gives an overview of the relative slowness
d277 1
a277 1
   <table>
d1228 1
a1228 2
  <table>
   <title>Credits</title>
d1280 1
a1280 1
  </table>
@


1.5
log
@pgcrypto doc updates

Marko Kreen
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.4 2008/01/05 13:17:00 petere Exp $ -->
d662 1
a662 1
    <productname>PostgreSQL<productname/> was built with zlib.
@


1.4
log
@Put spaces after "RFC".
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pgcrypto.sgml,v 1.3 2007/12/16 23:00:42 tgl Exp $ -->
d29 4
a32 2
    Standard algorithms are <literal>md5</literal> and
    <literal>sha1</literal>.  If <filename>pgcrypto</> was built with
d395 1
a395 1
   The functions here implement the encryption part of the OpenPGP (RFC 2440)
d662 1
a662 1
    <filename>pgcrypto</> was built with zlib.
d694 1
a694 1
    decrypting.  RFC 2440 specifies that text data should be stored using
d711 1
a711 1
    the addition of SHA-1 protected packets to RFC 2440.
d1177 1
a1177 1
     <para><ulink url="http://www.ietf.org/rfc/rfc2440.txt"></ulink></para>
a1180 6
     <para>
      <ulink url="http://www.imc.org/draft-ietf-openpgp-rfc2440bis"></ulink>
     </para>
     <para>New version of RFC 2440.</para>
    </listitem>
    <listitem>
@


1.3
log
@Make an editorial pass over the newly SGML-ified contrib documentation.
Fix lots of bad markup, bad English, bad explanations.

Last ones ... whew.  Man, that was tedious.
@
text
@d1 1
a1 1
<!-- $PostgreSQL$ -->
d393 1
a393 1
   The functions here implement the encryption part of the OpenPGP (RFC2440)
d692 1
a692 1
    decrypting.  RFC2440 specifies that text data should be stored using
d709 1
a709 1
    the addition of SHA-1 protected packets to RFC2440.
d1182 1
a1182 1
     <para>New version of RFC2440.</para>
@


1.2
log
@Remove tabs from SGML files.
@
text
@d1 1
d5 1
a5 1
 
d11 2
a12 1
  This module provides cryptographic functions for PostgreSQL.
d16 1
a16 108
  <title>Notes</title>
  <sect3>
   <title>Configuration</title>
   <para>
    pgcrypto configures itself according to the findings of main PostgreSQL
    <literal>configure</literal> script.  The options that affect it are 
    <literal>--with-zlib</literal> and <literal>--with-openssl</literal>.
   </para>
   <para>
    When compiled with zlib, PGP encryption functions are able to
    compress data before encrypting.
   </para>
   <para>
    When compiled with OpenSSL there will be more algorithms available.
    Also public-key encryption functions will be faster as OpenSSL
    has more optimized BIGNUM functions.
   </para>
   <para>
    Summary of functionality with and without OpenSSL:
   </para>
   <table>
    <title>Summary of functionality with and without OpenSSL</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Functionality</entry>
       <entry>built-in</entry>
       <entry>OpenSSL</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>MD5</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>SHA1</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>SHA224/256/384/512</entry>
       <entry>yes</entry>
       <entry>yes (3)</entry>
      </row>
      <row>
       <entry>Any other digest algo</entry>
       <entry>no</entry>
       <entry>yes (1)</entry>
      </row>
      <row>
       <entry>Blowfish</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>AES</entry>
       <entry>yes</entry>
       <entry>yes (2)</entry>
      </row>
      <row>
       <entry>DES/3DES/CAST5</entry>
       <entry>no</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>Raw encryption</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>PGP Symetric encryption</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
      <row>
       <entry>PGP Public-Key encryption</entry>
       <entry>yes</entry>
       <entry>yes</entry>
      </row>
     </tbody>
    </tgroup>
   </table>

   <orderedlist>
    <listitem>
     <para>
      Any digest algorithm OpenSSL supports is automatically picked up.
      This is not possible with ciphers, which need to be supported
      explicitly.
     </para>
    </listitem>
    <listitem>
     <para>
      AES is included in OpenSSL since version 0.9.7.  If pgcrypto is
      compiled against older version, it will use built-in AES code,
      so it has AES always available.
     </para>
    </listitem>
    <listitem>
     <para>
      SHA2 algorithms were added to OpenSSL in version 0.9.8.  For
      older versions, pgcrypto will use built-in code.
     </para>
    </listitem>
   </orderedlist>
  </sect3>
d19 1
a19 6
   <title>NULL handling</title>
   <para>
    As standard in SQL, all functions return NULL, if any of the arguments
    are NULL.  This may create security risks on careless usage.
   </para>
  </sect3>
d21 4
a24 7
  <sect3>
   <title>Security</title>
   <para>
    All the functions here run inside database server.  That means that all
    the data and passwords move between pgcrypto and client application in
    clear-text.  Thus you must:
   </para>
a25 8
   <orderedlist>
    <listitem>
     <para>Connect locally or use SSL connections.</para>
    </listitem>
    <listitem>
     <para>Trust both system and database administrator.</para>
    </listitem>
   </orderedlist>
d27 6
a32 1
    If you cannot, then better do crypto inside client application.
a33 2
  </sect3>
 </sect2>
a34 17
 <sect2>
  <title>General hashing</title>
  
  <sect3>
   <title><literal>digest(data, type)</literal></title>
   <programlisting>
    digest(data text, type text) RETURNS bytea
    digest(data bytea, type text) RETURNS bytea
   </programlisting>
   <para>
    Type is here the algorithm to use.  Standard algorithms are `md5` and
    `sha1`, although there may be more supported, depending on build
    options.
   </para>
   <para>
    Returns binary hash.
   </para>
d36 2
a37 1
    If you want hexadecimal string, use `encode()` on result.  Example:
d40 1
a40 1
    CREATE OR REPLACE FUNCTION sha1(bytea) RETURNS text AS $$
d47 7
a53 5
   <title><literal>hmac(data, key, type)</literal></title>
   <programlisting>
    hmac(data text, key text, type text) RETURNS bytea
    hmac(data bytea, key text, type text) RETURNS bytea
   </programlisting>
d55 2
a56 3
    Calculates Hashed MAC over data.  `type` is the same as in `digest()`.
    If the key is larger than hash block size it will first hashed and the
    hash will be used as key.
d58 1
d60 3
a62 3
    It is similar to digest() but the hash can be recalculated only knowing
    the key.  This avoids the scenario of someone altering data and also
    changing the hash.
d64 1
d66 2
a67 1
    Returns binary hash.
d73 2
a74 1
  <title>Password hashing</title>
d76 3
a78 2
   The functions <literal>crypt()</literal> and <literal>gen_salt()</literal> are specifically designed
   for hashing passwords.  <literal>crypt()</literal> does the hashing and `gen_salt()`
d81 1
d83 2
a84 2
   The algorithms in `crypt()` differ from usual hashing algorithms like
   MD5 or SHA1 in following respects:
d86 1
d90 1
a90 1
     They are slow.  As the amount of data is so small, this is only
d96 3
a98 3
     Include random 'salt' with result, so that users having same
     password would have different crypted passwords.  This is also
     additional defense against reversing the algorithm.
d103 1
a103 1
     Include algorithm type in the result, so passwords hashed with
d109 1
a109 1
     Some of them are adaptive - that means after computers get
d116 44
a159 13
  <para>
   Supported algorithms:
  </para>
  <programlisting>
`------`-------------`---------`----------`---------------------------
 Type   Max password  Adaptive  Salt bits  Description
----------------------------------------------------------------------
`bf`     72           yes         128      Blowfish-based, variant 2a
`md5`    unlimited    no           48      md5-based crypt()
`xdes`   8            yes          24      Extended DES
`des`    8            no           12      Original UNIX crypt
---------------------------------------------------------------------- 
  </programlisting>
d162 6
a167 4
   <title>crypt(password, salt)</title>
   <programlisting>
    crypt(password text, salt text) RETURNS text
   </programlisting>
d169 5
a173 3
    Calculates UN*X crypt(3) style hash of password.  When storing new
    password, you need to use function `gen_salt()` to generate new salt.
    When checking password you should use existing hash as salt.
d176 1
a176 1
    Example - setting new password:
d179 1
a179 1
    UPDATE .. SET pswhash = crypt('new password', gen_salt('md5'));
d182 1
a182 1
    Example - authentication:
d185 1
a185 1
    SELECT pswhash = crypt('entered password', pswhash) WHERE .. ;
d188 1
a188 2
    returns true or false whether the entered password is correct.
    It also can return NULL if `pswhash` field is NULL.
d193 6
a198 4
   <title>gen_salt(type)</title>
   <programlisting>
    gen_salt(type text) RETURNS text
   </programlisting>
d200 2
a201 2
    Generates a new random salt for usage in `crypt()`.  For adaptible
    algorithms, it uses the default iteration count.
d203 1
d205 3
a207 1
    Accepted types are: `des`, `xdes`, `md5` and `bf`.
d209 1
a209 6
  </sect3>
  <sect3>
   <title>gen_salt(type, rounds)</title>
   <programlisting>
    gen_salt(type text, rounds integer) RETURNS text
   </programlisting>
d211 3
a213 1
    algorithms.  The higher the count, the more time it takes to hash
d215 4
a218 2
    too high count the time to calculate a hash may be several years
    - which is somewhat impractical.
d220 29
d250 2
a251 1
    Number is algorithm specific:
d253 1
a253 8
   <programlisting>
`-----'---------'-----'----------
 type   default   min   max
---------------------------------
 `xdes`     725     1   16777215
 `bf`         6     4         31
--------------------------------- 
   </programlisting>
d255 5
a259 2
    In case of xdes there is a additional limitation that the count must be
    a odd number.
d261 1
d263 9
a271 1
    Notes:
a272 24
   <itemizedlist>
    <listitem>
     <para>
     Original DES crypt was designed to have the speed of 4 hashes per
     second on the hardware of that time.
     </para>
    </listitem>
    <listitem>
     <para>
     Slower than 4 hashes per second would probably dampen usability.
     </para>
    </listitem>
    <listitem>
     <para>
     Faster than 100 hashes per second is probably too fast.
     </para>
    </listitem>
    <listitem>
     <para>
     See next section about possible values for `crypt-bf`.
     </para>
    </listitem>
   </itemizedlist>
  </sect3>
d274 64
a337 2
  <sect3>
   <title>Comparison of crypt and regular hashes</title>
d339 1
a339 2
    Here is a table that should give overview of relative slowness
    of different hashing algorithms.
d341 1
d345 1
a345 39
     The goal is to crack a 8-character password, which consists:
     </para>
     <orderedlist>
      <listitem><para>Only of lowercase letters</para></listitem>
      <listitem><para>Numbers, lower- and uppercase letters.</para></listitem>
     </orderedlist>
    </listitem>
    <listitem>
     <para>
     The table below shows how much time it would take to try all
     combinations of characters.
     </para>
    </listitem>
    <listitem>
     <para>
     The <literal>crypt-bf</literal> is featured in several settings - the number
     after slash is the <literal>rounds</literal> parameter of 
     <literal>gen_salt()</literal>.
     </para>
    </listitem>
   </itemizedlist>
   <programlisting>
`------------'----------'--------------'--------------------
Algorithm     Hashes/sec  Chars: [a-z]   Chars: [A-Za-z0-9]
------------------------------------------------------------
crypt-bf/8            28     246 years         251322 years
crypt-bf/7            57     121 years         123457 years
crypt-bf/6           112      62 years          62831 years
crypt-bf/5           211      33 years          33351 years
crypt-md5           2681     2.6 years           2625 years
crypt-des         362837        7 days             19 years
sha1              590223        4 days             12 years
md5              2345086         1 day              3 years
------------------------------------------------------------
   </programlisting>
   <itemizedlist>
    <listitem>
     <para>
     The machine used is 1.5GHz Pentium 4.
d350 2
a351 2
     crypt-des and crypt-md5 algorithm numbers are taken from
     John the Ripper v1.6.38 `-test` output.
d356 1
a356 1
     MD5 numbers are from mdcrack 1.2.
d361 1
a361 1
     SHA1 numbers are from lcrack-20031130-beta.
d366 8
a373 6
     <literal>crypt-bf</literal> numbers are taken using simple program that loops
     over 1000 8-character passwords.  That way I can show the speed with
     different number of rounds.  For reference: <literal>john -test</literal>
     shows 213 loops/sec for crypt-bf/5.  (The small difference in results is 
     in accordance to the fact that the <literal>crypt-bf</literal> implementation in pgcrypto
     is same one that is used in John the Ripper.)
d379 1
a379 1
    Note that "try all combinations" is not a realistic exercise.
d383 1
a383 1
    numbers suggest, and a 6-character non-word like password may escape
d389 68
a457 2
 <sect2>
  <title>PGP encryption</title>
d459 1
a459 2
   The functions here implement the encryption part of OpenPGP (RFC2440)
   standard.   Supported are both symmetric-key and public-key encryption.
d461 24
d487 1
a487 40
   <title>Overview</title>
   <para>
    Encrypted PGP message consists of 2 packets:
   </para>
   <itemizedlist>
    <listitem><para>Packet for session key - either symmetric- or public-key encrypted.</para></listitem>
    <listitem><para>Packet for session-key encrypted data.</para></listitem>
   </itemizedlist>
   <para>
    When encrypting with password:
   </para>
   <orderedlist>
    <listitem>
     <para>
     Given password is hashed using String2Key (S2K) algorithm.  This
     is rather similar to `crypt()` algorithm - purposefully slow
     and with random salt - but it produces a full-length binary key.
     </para>
    </listitem>
    <listitem>
     <para>
     If separate session key is requested, new random key will be
     generated.  Otherwise S2K key will be used directly as session key.
     </para>
    </listitem>
    <listitem>
     <para>
     If S2K key is to be used directly, then only S2K settings will be put
     into session key packet.  Otherwise session key will be encrypted with
     S2K key and put into session key packet.
     </para>
    </listitem>
   </orderedlist>
   <para>
    When encrypting with public key:
   </para>
   <orderedlist>
    <listitem><para>New random session key is generated.</para></listitem>
    <listitem><para>It is encrypted using public key and put into session key packet.</para></listitem>
   </orderedlist>
d489 4
d494 3
a496 1
    Now common part, the session-key encrypted data packet:
a497 24
   <orderedlist>
    <listitem> 
     <para>
     Optional data-manipulation: compression, conversion to UTF-8,
     conversion of line-endings.
     </para>
    </listitem>
    <listitem>
     <para>
     Data is prefixed with block of random bytes.  This is equal
     to using random IV.
     </para>
    </listitem>
    <listitem>
     <para>
     A SHA1 hash of random prefix and data is appended.
     </para>
    </listitem>
    <listitem>
     <para>
     All this is encrypted with session key.
     </para>
    </listitem>
   </orderedlist>
d501 1
a501 12
   <title><literal>pgp_sym_encrypt(data, psw)</literal></title>
   <programlisting>
    pgp_sym_encrypt(data text, psw text [, options text] ) RETURNS bytea
    pgp_sym_encrypt_bytea(data bytea, psw text [, options text] ) RETURNS bytea
   </programlisting>
   <para>
    Return a symmetric-key encrypted PGP message.
   </para>
   <para>
    Options are described in section 5.8.
   </para>
  </sect3>
d503 4
a506 6
  <sect3>
   <title><literal>pgp_sym_decrypt(msg, psw)</literal></title>
   <programlisting>
    pgp_sym_decrypt(msg bytea, psw text [, options text] ) RETURNS text
    pgp_sym_decrypt_bytea(msg bytea, psw text [, options text] ) RETURNS bytea
   </programlisting>
d508 1
a508 1
    Decrypt a symmetric-key encrypted PGP message.
d511 1
a511 1
    Decrypting bytea data with `pgp_sym_decrypt` is disallowed.
d513 1
a513 1
    originally textual data with `pgp_sym_decrypt_bytea` is fine.
d516 2
a517 1
    Options are described in section 5.8.
d522 6
a527 5
   <title><literal>pgp_pub_encrypt(data, pub_key)</literal></title>
   <programlisting>
    pgp_pub_encrypt(data text, key bytea [, options text] ) RETURNS bytea
    pgp_pub_encrypt_bytea(data bytea, key bytea [, options text] ) RETURNS bytea
   </programlisting>
d529 2
a530 2
    Encrypt data with a public key.  Giving this function a secret key will
    produce a error.
d533 2
a534 1
    Options are described in section 5.8.
d539 6
a544 5
   <title><literal>pgp_pub_decrypt(msg, sec_key [, psw])</literal></title>
   <programlisting>
    pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text]] ) RETURNS text
    pgp_pub_decrypt_bytea(msg bytea, key bytea [,psw text [, options text]] ) RETURNS bytea
   </programlisting>
d546 5
a550 4
    Decrypt a public-key encrypted message with secret key.  If the secret
    key is password-protected, you must give the password in `psw`.  If
    there is no password, but you want to specify option for function, you
    need to give empty password.
d553 1
a553 1
    Decrypting bytea data with `pgp_pub_decrypt` is disallowed.
d555 1
a555 1
    originally textual data with `pgp_pub_decrypt_bytea` is fine.
d558 2
a559 1
    Options are described in section 5.8.
d564 5
a568 4
   <title><literal>pgp_key_id(key / msg)</literal></title>
   <programlisting>
    pgp_key_id(key or msg bytea) RETURNS text
   </programlisting>
d570 3
a572 3
    It shows you either key ID if given PGP public or secret key.  Or it
    gives the key ID that was used for encrypting the data, if given
    encrypted message.
d580 1
a580 1
      SYMKEY:
d583 1
a583 1
      The data is encrypted with symmetric key.
d588 1
a588 1
      ANYKEY:
d591 4
a594 4
      The data is public-key encrypted, but the key ID is cleared.
      That means you need to try all your secret keys on it to see
      which one decrypts it.  pgcrypto itself does not produce such
      messages.
d599 3
a601 3
    Note that different keys may have same ID.   This is rare but normal
    event.  Client application should then try to decrypt with each one,
    to see which fits - like handling ANYKEY.
d606 6
a611 5
   <title><literal>armor / dearmor</literal></title>
   <programlisting>
    armor(data bytea) RETURNS text
    dearmor(data text) RETURNS bytea
   </programlisting>
d613 2
a614 2
    Those wrap/unwrap data into PGP Ascii Armor which is basically Base64
    with CRC and additional formatting.
d620 1
d622 3
a624 2
    Options are named to be similar to GnuPG.  Values should be given after
    an equal sign; separate options from each other with commas.  Example:
d629 1
d631 3
a633 2
    All of the options except `convert-crlf` apply only to encrypt
    functions.  Decrypt functions get the parameters from PGP data.
d635 1
d637 3
a639 2
    Most interesting options are probably `compression-algo` and
    <literal>unicode-mode</literal>.  The rest should have reasonable defaults.
a640 1
  </sect3>
d642 1
a642 1
  <sect3>
d644 1
d646 1
a646 1
    What cipher algorithm to use.
d649 1
a649 1
    Values: bf, aes128, aes192, aes256 (OpenSSL-only: `3des`, `cast5`)
d651 1
a651 1
    Applies: pgp_sym_encrypt, pgp_pub_encrypt
d653 1
a653 1
  </sect3>
d655 1
a655 1
  <sect3>
d657 1
d659 2
a660 1
    Which compression algorithm to use.  Needs building with zlib.
d662 1
a662 1
   <para>
d664 3
a666 5
   </para>
   <programlisting>
    0 - no compression
    1 - ZIP compression
    2 - ZLIB compression [=ZIP plus meta-data and block-CRC's]
d668 1
a668 1
    Applies: pgp_sym_encrypt, pgp_pub_encrypt
d670 1
a670 1
  </sect3>
d672 1
a672 1
  <sect3>
d674 1
d676 1
a676 1
    How much to compress.  Bigger level compresses smaller but is slower.
d682 1
a682 1
    Applies: pgp_sym_encrypt, pgp_pub_encrypt
d684 1
a684 1
  </sect3>
d686 1
a686 1
  <sect3>
d688 1
d690 4
a693 3
    Whether to convert `\n` into `\r\n` when encrypting and `\r\n` to `\n`
    when decrypting.  RFC2440 specifies that text data should be stored
    using `\r\n` line-feeds.  Use this to get fully RFC-compliant
d699 1
a699 1
    Applies: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt
d701 1
a701 1
  </sect3>
d703 1
a703 1
  <sect3>
d705 1
d707 4
a710 5
    Do not protect data with SHA-1.  Only good reason to use this
    option is to achieve compatibility with ancient PGP products, as the
    SHA-1 protected packet is from upcoming update to RFC2440.  (Currently
    at version RFC2440bis-14.) Recent gnupg.org and pgp.com software
    supports it fine.
d715 1
a715 1
    Applies: pgp_sym_encrypt, pgp_pub_encrypt
d717 1
a717 1
  </sect3>
d719 1
a719 1
  <sect3>
d721 1
d723 3
a725 3
    Use separate session key.  Public-key encryption always uses separate
    session key, this is for symmetric-key encryption, which by default
    uses S2K directly.
d730 1
a730 1
    Applies: pgp_sym_encrypt
d732 1
a732 1
  </sect3>
d734 1
a734 1
  <sect3>
d736 1
d746 1
a746 1
    Applies: pgp_sym_encrypt
d748 1
a748 1
  </sect3>
d750 1
a750 1
  <sect3>
d752 1
d759 1
a759 1
    Applies: pgp_sym_encrypt
d761 1
a761 1
  </sect3>
d763 1
a763 1
  <sect3>
d765 1
d771 2
a772 2
    Default: use cipher-algo.
    Applies: pgp_sym_encrypt
d774 1
a774 1
  </sect3>
d776 1
a776 1
  <sect3>
d778 1
d782 1
a782 1
    be done, only the data will be tagged as UTF-8.  Without this option
d788 1
a788 1
    Applies: pgp_sym_encrypt, pgp_pub_encrypt
d790 1
a791 1
 </sect2>
d793 3
a795 2
 <sect2>
  <title>Generating keys with GnuPG</title>
d797 1
a797 1
   Generate a new key:
d803 1
a803 1
   The preferred key type is "DSA and Elgamal".
d807 2
a808 1
   as master and then add RSA encryption subkey with `gpg --edit-key`.
d811 1
a811 1
   List keys:
d817 1
a817 1
   Export ascii-armored public key:
d823 1
a823 1
   Export ascii-armored secret key:
d828 4
a831 4
  <para> 
   You need to use `dearmor()` on them before giving them to
   pgp_pub_* functions.  Or if you can handle binary data, you can drop
   "-a" from gpg.
d834 4
a837 4
   For more details see `man gpg`, 
   <ulink url="http://www.gnupg.org/gph/en/manual.html"></ulink>[The GNU 
   Privacy Handbook] and other docs on 
   <ulink url="http://www.gnupg.org"></ulink> site.
d839 1
a839 1
 </sect2>
d841 1
a841 1
 <sect2>
d843 1
d848 1
a848 1
    whether the encryption subkey belongs to master key.
d854 1
a854 1
    is generally discouraged, it should not be a problem.
d861 2
a862 2
    GPG/PGP keys with pgcrypto, but create new ones, as the usage scenario
    is rather different.
d866 1
d870 2
a871 1
  <title>Raw encryption</title>
d873 1
a873 1
   Those functions only run a cipher over data, they don't have any advanced
a903 3
  <programlisting>
    encrypt(data bytea, key bytea, type text) RETURNS bytea
    decrypt(data bytea, key bytea, type text) RETURNS bytea
d905 8
a912 3
    encrypt_iv(data bytea, key bytea, iv bytea, type text) RETURNS bytea
    decrypt_iv(data bytea, key bytea, iv bytea, type text) RETURNS bytea
  </programlisting>
d914 3
a916 1
   Encrypt/decrypt data with cipher, padding data if needed.
d918 5
d924 1
a924 7
   <literal>type</literal> parameter description in pseudo-noteup:
  </para>
  <programlisting>
    algo ['-' mode] ['/pad:' padding]
  </programlisting>
  <para>
   Supported algorithms:
d927 2
a928 2
   <listitem><para><literal>bf</literal>- Blowfish</para></listitem>
   <listitem><para><literal>aes</literal>- AES (Rijndael-128)</para></listitem>
d931 1
a931 1
   Modes:
d936 1
a936 1
    <literal>cbc</literal>- next block depends on previous. (default)
d941 2
a942 2
    <literal>ecb</literal>- each block is encrypted separately. (for testing 
    only)
d947 1
a947 1
   Padding:
d952 1
a952 1
    <literal>pkcs</literal>-data may be any length (default)
d957 1
a957 1
    <literal>none</literal>- data must be multiple of cipher block size.
d962 1
a962 5
   IV is initial value for mode, defaults to all zeroes.  It is ignored for
   ECB.  It is clipped or padded with zeroes if not exactly block size.
  </para>
  <para>
   So, example:
d966 1
d969 5
a973 1
   is equal to
a974 3
  <programlisting>
   encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
  </programlisting>
d978 5
a982 4
  <title>Random bytes</title>
  <programlisting>
    gen_random_bytes(count integer)
  </programlisting>
d984 2
a985 2
   Returns `count` cryptographically strong random bytes as bytea value.
   There can be maximally 1024 bytes extracted at a time.  This is to avoid
d991 148
a1138 2
  <title>References/Links</title>
  
d1141 1
d1144 2
a1145 2
     <para><ulink url="http://www.gnupg.org/gph/en/manual.html"></ulink>:</para>
     <para>The GNU Privacy Handbook</para>
d1148 1
a1148 1
     <para><ulink url="http://www.openwall.com/crypt/"></ulink>:</para>
d1153 1
a1153 1
      <ulink url="http://www.stack.nl/~galactus/remailers/passphrase-faq.html"></ulink>:
d1155 1
a1155 1
     <para>How to choose good password.</para>
d1158 1
a1158 1
     <para><ulink url="http://world.std.com/~reinhold/diceware.html"></ulink>:</para>
d1163 1
a1163 1
      <ulink url="http://www.interhack.net/people/cmcurtin/snake-oil-faq.html"></ulink>:
d1172 1
d1175 2
a1176 2
     <para><ulink url="http://www.ietf.org/rfc/rfc2440.txt"></ulink>:</para>
     <para>OpenPGP message format</para>
d1180 1
a1180 1
      <ulink url="http://www.imc.org/draft-ietf-openpgp-rfc2440bis"></ulink>:
d1185 2
a1186 2
     <para><ulink url="http://www.ietf.org/rfc/rfc1321.txt"></ulink>:</para>
     <para>The MD5 Message-Digest Algorithm</para>
d1189 2
a1190 2
     <para><ulink url="http://www.ietf.org/rfc/rfc2104.txt"></ulink>:</para>
     <para>HMAC: Keyed-Hashing for Message Authentication</para>
d1194 1
a1194 1
      <ulink url="http://www.usenix.org/events/usenix99/provos.html"></ulink>:
d1199 1
a1199 1
     <para><ulink url="http://csrc.nist.gov/cryptval/des.htm"></ulink>:</para>
d1204 1
a1204 1
      <ulink url="http://en.wikipedia.org/wiki/Fortuna_(PRNG)"></ulink>:
d1209 1
a1209 1
     <para><ulink url="http://jlcooke.ca/random/"></ulink>:</para>
d1213 1
a1213 1
     <para><ulink url="http://www.cs.ut.ee/~helger/crypto/"></ulink>:</para>
d1221 6
a1226 1
  <title>Credits</title>
d1228 1
a1228 1
   <literal>pgcrypto</literal> uses code from the following sources:
d1230 1
d1236 3
a1238 3
      <entry><para>Algorithm</para></entry>
      <entry><para>Author</para></entry>
      <entry><para>Source origin</para></entry>
d1243 3
a1245 3
      <entry><para>DES crypt()</para></entry>
      <entry><para>David Burren and others</para></entry>
      <entry><para>FreeBSD libcrypt</para></entry>
d1248 3
a1250 3
      <entry><para>MD5 crypt()</para></entry> 
      <entry><para>Poul-Henning Kamp</para></entry>        
      <entry><para>FreeBSD libcrypt</para></entry>
d1253 3
a1255 3
      <entry><para>Blowfish crypt()</para></entry>     
      <entry><para>Solar Designer</para></entry>            
      <entry><para>www.openwall.com</para></entry>
d1258 3
a1260 3
      <entry><para>Blowfish cipher</para></entry>     
      <entry><para>Simon Tatham</para></entry>
      <entry><para>PuTTY</para></entry>
d1263 3
a1265 3
      <entry><para>Rijndael cipher</para></entry>     
      <entry><para>Brian Gladman</para></entry>
      <entry><para>OpenBSD sys/crypto</para></entry>
d1268 3
a1270 3
      <entry><para>MD5 and SHA1</para></entry>        
      <entry><para>WIDE Project</para></entry>
      <entry><para>KAME kame/sys/crypto</para></entry>
d1273 3
a1275 3
      <entry><para>SHA256/384/512 </para></entry>      
      <entry><para>Aaron D. Gifford</para></entry>
      <entry><para>OpenBSD sys/crypto</para></entry>
d1278 3
a1280 3
      <entry><para>BIGNUM math</para></entry>          
      <entry><para>Michael J. Fromberger</para></entry>
      <entry><para>dartmouth.edu/~sting/sw/imath</para></entry>
a1286 7
 <sect2>
  <title>Author</title>
  <para>
   Marko Kreen <email>markokr@@gmail.com</email>
  </para>
 </sect2>
 
a1287 1

@


1.1
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@d959 1
a959 1
    <literal>none</literal>- data must be multiple of cipher block size.	
@

