doc/src/sgml/pgcrypto.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect1 id="pgcrypto">
   4  <title>pgcrypto</title>
   5
   6  <indexterm zone="pgcrypto">
   7   <primary>pgcrypto</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>pgcrypto</> module provides cryptographic functions for
  12   <productname>PostgreSQL</>.
  13  </para>
  14
  15  <sect2>
  16   <title>General hashing functions</title>
  17
  18   <sect3>
  19    <title><function>digest()</function></title>
  20
  21    <synopsis>
  22     digest(data text, type text) returns bytea
  23     digest(data bytea, type text) returns bytea
  24    </synopsis>
  25
  26    <para>
  27     Computes a binary hash of the given <parameter>data</>.
  28     <parameter>type</> is the algorithm to use.
  29     Standard algorithms are <literal>md5</literal>, <literal>sha1</literal>,
  30     <literal>sha224</literal>, <literal>sha256</literal>,
  31     <literal>sha384</literal> and <literal>sha512</literal>.
  32     If <filename>pgcrypto</> was built with
  33     OpenSSL, more algorithms are available, as detailed in
  34     <xref linkend="pgcrypto-with-without-openssl">.
  35    </para>
  36
  37    <para>
  38     If you want the digest as a hexadecimal string, use
  39     <function>encode()</> on the result.  For example:
  40    </para>
  41    <programlisting>
  42     CREATE OR REPLACE FUNCTION sha1(bytea) returns text AS $$
  43       SELECT encode(digest($1, 'sha1'), 'hex')
  44     $$ LANGUAGE SQL STRICT IMMUTABLE;
  45    </programlisting>
  46   </sect3>
  47
  48   <sect3>
  49    <title><function>hmac()</function></title>
  50
  51    <synopsis>
  52     hmac(data text, key text, type text) returns bytea
  53     hmac(data bytea, key text, type text) returns bytea
  54    </synopsis>
  55
  56    <para>
  57     Calculates hashed MAC for <parameter>data</> with key <parameter>key</>.
  58     <parameter>type</> is the same as in <function>digest()</>.
  59    </para>
  60
  61    <para>
  62     This is similar to <function>digest()</> but the hash can only be
  63     recalculated knowing the key.  This prevents the scenario of someone
  64     altering data and also changing the hash to match.
  65    </para>
  66
  67    <para>
  68     If the key is larger than the hash block size it will first be hashed and
  69     the result will be used as key.
  70    </para>
  71   </sect3>
  72  </sect2>
  73
  74  <sect2>
  75   <title>Password hashing functions</title>
  76
  77   <para>
  78    The functions <function>crypt()</> and <function>gen_salt()</>
  79    are specifically designed for hashing passwords.
  80    <function>crypt()</> does the hashing and <function>gen_salt()</>
  81    prepares algorithm parameters for it.
  82   </para>
  83
  84   <para>
  85    The algorithms in <function>crypt()</> differ from usual hashing algorithms
  86    like MD5 or SHA1 in the following respects:
  87   </para>
  88
  89   <orderedlist>
  90    <listitem>
  91     <para>
  92      They are slow.  As the amount of data is so small, this is the only
  93      way to make brute-forcing passwords hard.
  94     </para>
  95    </listitem>
  96    <listitem>
  97     <para>
  98      They use a random value, called the <firstterm>salt</>, so that users
  99      having the same password will have different encrypted passwords.
 100      This is also an additional defense against reversing the algorithm.
 101     </para>
 102    </listitem>
 103    <listitem>
 104     <para>
 105      They include the algorithm type in the result, so passwords hashed with
 106      different algorithms can co-exist.
 107     </para>
 108    </listitem>
 109    <listitem>
 110     <para>
 111      Some of them are adaptive &mdash; that means when computers get
 112      faster, you can tune the algorithm to be slower, without
 113      introducing incompatibility with existing passwords.
 114     </para>
 115    </listitem>
 116   </orderedlist>
 117
 118   <table>
 119    <title>Supported algorithms for <function>crypt()</></title>
 120    <tgroup cols="5">
 121     <thead>
 122      <row>
 123       <entry>Algorithm</entry>
 124       <entry>Max password length</entry>
 125       <entry>Adaptive?</entry>
 126       <entry>Salt bits</entry>
 127       <entry>Description</entry>
 128      </row>
 129     </thead>
 130     <tbody>
 131      <row>
 132       <entry><literal>bf</></entry>
 133       <entry>72</entry>
 134       <entry>yes</entry>
 135       <entry>128</entry>
 136       <entry>Blowfish-based, variant 2a</entry>
 137      </row>
 138      <row>
 139       <entry><literal>md5</></entry>
 140       <entry>unlimited</entry>
 141       <entry>no</entry>
 142       <entry>48</entry>
 143       <entry>MD5-based crypt</entry>
 144      </row>
 145      <row>
 146       <entry><literal>xdes</></entry>
 147       <entry>8</entry>
 148       <entry>yes</entry>
 149       <entry>24</entry>
 150       <entry>Extended DES</entry>
 151      </row>
 152      <row>
 153       <entry><literal>des</></entry>
 154       <entry>8</entry>
 155       <entry>no</entry>
 156       <entry>12</entry>
 157       <entry>Original UNIX crypt</entry>
 158      </row>
 159     </tbody>
 160    </tgroup>
 161   </table>
 162
 163   <sect3>
 164    <title><function>crypt()</></title>
 165
 166    <synopsis>
 167     crypt(password text, salt text) returns text
 168    </synopsis>
 169
 170    <para>
 171     Calculates a crypt(3)-style hash of <parameter>password</>.
 172     When storing a new password, you need to use
 173     <function>gen_salt()</> to generate a new <parameter>salt</> value.
 174     To check a password, pass the stored hash value as <parameter>salt</>,
 175     and test whether the result matches the stored value.
 176    </para>
 177    <para>
 178     Example of setting a new password:
 179    </para>
 180    <programlisting>
 181     UPDATE ... SET pswhash = crypt('new password', gen_salt('md5'));
 182    </programlisting>
 183    <para>
 184     Example of authentication:
 185    </para>
 186    <programlisting>
 187     SELECT pswhash = crypt('entered password', pswhash) FROM ... ;
 188    </programlisting>
 189    <para>
 190     This returns <literal>true</> if the entered password is correct.
 191    </para>
 192   </sect3>
 193
 194   <sect3>
 195    <title><function>gen_salt()</></title>
 196
 197    <synopsis>
 198     gen_salt(type text [, iter_count integer ]) returns text
 199    </synopsis>
 200
 201    <para>
 202     Generates a new random salt string for use in <function>crypt()</>.
 203     The salt string also tells <function>crypt()</> which algorithm to use.
 204    </para>
 205
 206    <para>
 207     The <parameter>type</> parameter specifies the hashing algorithm.
 208     The accepted types are: <literal>des</literal>, <literal>xdes</literal>,
 209     <literal>md5</literal> and <literal>bf</literal>.
 210    </para>
 211
 212    <para>
 213     The <parameter>iter_count</> parameter lets the user specify the iteration
 214     count, for algorithms that have one.
 215     The higher the count, the more time it takes to hash
 216     the password and therefore the more time to break it.  Although with
 217     too high a count the time to calculate a hash may be several years
 218     &mdash; which is somewhat impractical.  If the <parameter>iter_count</>
 219     parameter is omitted, the default iteration count is used.
 220     Allowed values for <parameter>iter_count</> depend on the algorithm and
 221     are shown in <xref linkend="pgcrypto-icfc-table">.
 222    </para>
 223
 224    <table id="pgcrypto-icfc-table">
 225     <title>Iteration counts for <function>crypt()</></title>
 226     <tgroup cols="4">
 227      <thead>
 228       <row>
 229        <entry>Algorithm</entry>
 230        <entry>Default</entry>
 231        <entry>Min</entry>
 232        <entry>Max</entry>
 233       </row>
 234      </thead>
 235      <tbody>
 236       <row>
 237        <entry><literal>xdes</></entry>
 238        <entry>725</entry>
 239        <entry>1</entry>
 240        <entry>16777215</entry>
 241       </row>
 242       <row>
 243        <entry><literal>bf</></entry>
 244        <entry>6</entry>
 245        <entry>4</entry>
 246        <entry>31</entry>
 247       </row>
 248      </tbody>
 249     </tgroup>
 250    </table>
 251
 252    <para>
 253     For <literal>xdes</literal> there is an additional limitation that the
 254     iteration count must be an odd number.
 255    </para>
 256
 257    <para>
 258     To pick an appropriate iteration count, consider that
 259     the original DES crypt was designed to have the speed of 4 hashes per
 260     second on the hardware of that time.
 261     Slower than 4 hashes per second would probably dampen usability.
 262     Faster than 100 hashes per second is probably too fast.
 263    </para>
 264
 265    <para>
 266     <xref linkend="pgcrypto-hash-speed-table"> gives an overview of the relative slowness
 267     of different hashing algorithms.
 268     The table shows how much time it would take to try all
 269     combinations of characters in an 8-character password, assuming
 270     that the password contains either only lowercase letters, or
 271     upper- and lower-case letters and numbers.
 272     In the <literal>crypt-bf</literal> entries, the number after a slash is
 273     the <parameter>iter_count</parameter> parameter of
 274     <function>gen_salt</function>.
 275    </para>
 276
 277    <table id="pgcrypto-hash-speed-table">
 278     <title>Hash algorithm speeds</title>
 279     <tgroup cols="4">
 280      <thead>
 281       <row>
 282        <entry>Algorithm</entry>
 283        <entry>Hashes/sec</entry>
 284        <entry>For <literal>[a-z]</></entry>
 285        <entry>For <literal>[A-Za-z0-9]</></entry>
 286       </row>
 287      </thead>
 288      <tbody>
 289       <row>
 290        <entry><literal>crypt-bf/8</></entry>
 291        <entry>28</entry>
 292        <entry>246 years</entry>
 293        <entry>251322 years</entry>
 294       </row>
 295       <row>
 296        <entry><literal>crypt-bf/7</></entry>
 297        <entry>57</entry>
 298        <entry>121 years</entry>
 299        <entry>123457 years</entry>
 300       </row>
 301       <row>
 302        <entry><literal>crypt-bf/6</></entry>
 303        <entry>112</entry>
 304        <entry>62 years</entry>
 305        <entry>62831 years</entry>
 306       </row>
 307       <row>
 308        <entry><literal>crypt-bf/5</></entry>
 309        <entry>211</entry>
 310        <entry>33 years</entry>
 311        <entry>33351 years</entry>
 312       </row>
 313       <row>
 314        <entry><literal>crypt-md5</></entry>
 315        <entry>2681</entry>
 316        <entry>2.6 years</entry>
 317        <entry>2625 years</entry>
 318       </row>
 319       <row>
 320        <entry><literal>crypt-des</></entry>
 321        <entry>362837</entry>
 322        <entry>7 days</entry>
 323        <entry>19 years</entry>
 324       </row>
 325       <row>
 326        <entry><literal>sha1</></entry>
 327        <entry>590223</entry>
 328        <entry>4 days</entry>
 329        <entry>12 years</entry>
 330       </row>
 331       <row>
 332        <entry><literal>md5</></entry>
 333        <entry>2345086</entry>
 334        <entry>1 day</entry>
 335        <entry>3 years</entry>
 336       </row>
 337      </tbody>
 338     </tgroup>
 339    </table>
 340
 341    <para>
 342     Notes:
 343    </para>
 344
 345    <itemizedlist>
 346     <listitem>
 347      <para>
 348      The machine used is a 1.5GHz Pentium 4.
 349      </para>
 350     </listitem>
 351     <listitem>
 352      <para>
 353       <literal>crypt-des</> and <literal>crypt-md5</> algorithm numbers are
 354       taken from John the Ripper v1.6.38 <literal>-test</> output.
 355      </para>
 356     </listitem>
 357     <listitem>
 358      <para>
 359       <literal>md5</> numbers are from mdcrack 1.2.
 360      </para>
 361     </listitem>
 362     <listitem>
 363      <para>
 364       <literal>sha1</> numbers are from lcrack-20031130-beta.
 365      </para>
 366     </listitem>
 367     <listitem>
 368      <para>
 369       <literal>crypt-bf</literal> numbers are taken using a simple program that
 370       loops over 1000 8-character passwords.  That way I can show the speed
 371       with different numbers of iterations.  For reference: <literal>john
 372       -test</literal> shows 213 loops/sec for <literal>crypt-bf/5</>.
 373       (The very small
 374       difference in results is in accordance with the fact that the
 375       <literal>crypt-bf</literal> implementation in <filename>pgcrypto</>
 376       is the same one used in John the Ripper.)
 377      </para>
 378     </listitem>
 379    </itemizedlist>
 380
 381    <para>
 382     Note that <quote>try all combinations</quote> is not a realistic exercise.
 383     Usually password cracking is done with the help of dictionaries, which
 384     contain both regular words and various mutations of them.  So, even
 385     somewhat word-like passwords could be cracked much faster than the above
 386     numbers suggest, while a 6-character non-word-like password may escape
 387     cracking.  Or not.
 388    </para>
 389   </sect3>
 390  </sect2>
 391
 392  <sect2>
 393   <title>PGP encryption functions</title>
 394
 395   <para>
 396    The functions here implement the encryption part of the OpenPGP (RFC 4880)
 397    standard.  Supported are both symmetric-key and public-key encryption.
 398   </para>
 399
 400   <para>
 401    An encrypted PGP message consists of 2 parts, or <firstterm>packets</>:
 402   </para>
 403   <itemizedlist>
 404    <listitem>
 405     <para>
 406      Packet containing a session key &mdash; either symmetric-key or public-key
 407      encrypted.
 408     </para>
 409    </listitem>
 410    <listitem>
 411     <para>
 412      Packet containing data encrypted with the session key.
 413     </para>
 414    </listitem>
 415   </itemizedlist>
 416
 417   <para>
 418    When encrypting with a symmetric key (i.e., a password):
 419   </para>
 420   <orderedlist>
 421    <listitem>
 422     <para>
 423      The given password is hashed using a String2Key (S2K) algorithm.  This is
 424      rather similar to <function>crypt()</> algorithms &mdash; purposefully
 425      slow and with random salt &mdash; but it produces a full-length binary
 426      key.
 427     </para>
 428    </listitem>
 429    <listitem>
 430     <para>
 431      If a separate session key is requested, a new random key will be
 432      generated.  Otherwise the S2K key will be used directly as the session
 433      key.
 434     </para>
 435    </listitem>
 436    <listitem>
 437     <para>
 438      If the S2K key is to be used directly, then only S2K settings will be put
 439      into the session key packet.  Otherwise the session key will be encrypted
 440      with the S2K key and put into the session key packet.
 441     </para>
 442    </listitem>
 443   </orderedlist>
 444
 445   <para>
 446    When encrypting with a public key:
 447   </para>
 448   <orderedlist>
 449    <listitem>
 450     <para>
 451      A new random session key is generated.
 452     </para>
 453    </listitem>
 454    <listitem>
 455     <para>
 456      It is encrypted using the public key and put into the session key packet.
 457     </para>
 458    </listitem>
 459   </orderedlist>
 460
 461   <para>
 462    In either case the data to be encrypted is processed as follows:
 463   </para>
 464   <orderedlist>
 465    <listitem>
 466     <para>
 467      Optional data-manipulation: compression, conversion to UTF-8,
 468      and/or conversion of line-endings.
 469     </para>
 470    </listitem>
 471    <listitem>
 472     <para>
 473      The data is prefixed with a block of random bytes.  This is equivalent
 474      to using a random IV.
 475     </para>
 476    </listitem>
 477    <listitem>
 478     <para>
 479      An SHA1 hash of the random prefix and data is appended.
 480     </para>
 481    </listitem>
 482    <listitem>
 483     <para>
 484      All this is encrypted with the session key and placed in the data packet.
 485     </para>
 486    </listitem>
 487   </orderedlist>
 488
 489   <sect3>
 490    <title><function>pgp_sym_encrypt()</function></title>
 491
 492    <synopsis>
 493     pgp_sym_encrypt(data text, psw text [, options text ]) returns bytea
 494     pgp_sym_encrypt_bytea(data bytea, psw text [, options text ]) returns bytea
 495    </synopsis>
 496    <para>
 497     Encrypt <parameter>data</> with a symmetric PGP key <parameter>psw</>.
 498     The <parameter>options</> parameter can contain option settings,
 499     as described below.
 500    </para>
 501   </sect3>
 502
 503   <sect3>
 504    <title><function>pgp_sym_decrypt()</function></title>
 505
 506    <synopsis>
 507     pgp_sym_decrypt(msg bytea, psw text [, options text ]) returns text
 508     pgp_sym_decrypt_bytea(msg bytea, psw text [, options text ]) returns bytea
 509    </synopsis>
 510    <para>
 511     Decrypt a symmetric-key-encrypted PGP message.
 512    </para>
 513    <para>
 514     Decrypting bytea data with <function>pgp_sym_decrypt</> is disallowed.
 515     This is to avoid outputting invalid character data.  Decrypting
 516     originally textual data with <function>pgp_sym_decrypt_bytea</> is fine.
 517    </para>
 518    <para>
 519     The <parameter>options</> parameter can contain option settings,
 520     as described below.
 521    </para>
 522   </sect3>
 523
 524   <sect3>
 525    <title><function>pgp_pub_encrypt()</function></title>
 526
 527    <synopsis>
 528     pgp_pub_encrypt(data text, key bytea [, options text ]) returns bytea
 529     pgp_pub_encrypt_bytea(data bytea, key bytea [, options text ]) returns bytea
 530    </synopsis>
 531    <para>
 532     Encrypt <parameter>data</> with a public PGP key <parameter>key</>.
 533     Giving this function a secret key will produce a error.
 534    </para>
 535    <para>
 536     The <parameter>options</> parameter can contain option settings,
 537     as described below.
 538    </para>
 539   </sect3>
 540
 541   <sect3>
 542    <title><function>pgp_pub_decrypt()</function></title>
 543
 544    <synopsis>
 545     pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text ]]) returns text
 546     pgp_pub_decrypt_bytea(msg bytea, key bytea [, psw text [, options text ]]) returns bytea
 547    </synopsis>
 548    <para>
 549     Decrypt a public-key-encrypted message.  <parameter>key</> must be the
 550     secret key corresponding to the public key that was used to encrypt.
 551     If the secret key is password-protected, you must give the password in
 552     <parameter>psw</>.  If there is no password, but you want to specify
 553     options, you need to give an empty password.
 554    </para>
 555    <para>
 556     Decrypting bytea data with <function>pgp_pub_decrypt</> is disallowed.
 557     This is to avoid outputting invalid character data.  Decrypting
 558     originally textual data with <function>pgp_pub_decrypt_bytea</> is fine.
 559    </para>
 560    <para>
 561     The <parameter>options</> parameter can contain option settings,
 562     as described below.
 563    </para>
 564   </sect3>
 565
 566   <sect3>
 567    <title><function>pgp_key_id()</function></title>
 568
 569    <synopsis>
 570     pgp_key_id(bytea) returns text
 571    </synopsis>
 572    <para>
 573     <function>pgp_key_id</> extracts the key ID of a PGP public or secret key.
 574     Or it gives the key ID that was used for encrypting the data, if given
 575     an encrypted message.
 576    </para>
 577    <para>
 578     It can return 2 special key IDs:
 579    </para>
 580    <itemizedlist>
 581     <listitem>
 582      <para>
 583       <literal>SYMKEY</>
 584      </para>
 585      <para>
 586       The message is encrypted with a symmetric key.
 587      </para>
 588     </listitem>
 589     <listitem>
 590      <para>
 591       <literal>ANYKEY</>
 592      </para>
 593      <para>
 594       The message is public-key encrypted, but the key ID has been removed.
 595       That means you will need to try all your secret keys on it to see
 596       which one decrypts it.  <filename>pgcrypto</> itself does not produce
 597       such messages.
 598      </para>
 599     </listitem>
 600    </itemizedlist>
 601    <para>
 602     Note that different keys may have the same ID.   This is rare but a normal
 603     event. The client application should then try to decrypt with each one,
 604     to see which fits &mdash; like handling <literal>ANYKEY</>.
 605    </para>
 606   </sect3>
 607
 608   <sect3>
 609    <title><function>armor()</function>, <function>dearmor()</function></title>
 610
 611    <synopsis>
 612     armor(data bytea) returns text
 613     dearmor(data text) returns bytea
 614    </synopsis>
 615    <para>
 616     These functions wrap/unwrap binary data into PGP Ascii Armor format,
 617     which is basically Base64 with CRC and additional formatting.
 618    </para>
 619   </sect3>
 620
 621   <sect3>
 622    <title>Options for PGP functions</title>
 623
 624    <para>
 625     Options are named to be similar to GnuPG.  An option's value should be
 626     given after an equal sign; separate options from each other with commas.
 627     For example:
 628    </para>
 629    <programlisting>
 630     pgp_sym_encrypt(data, psw, 'compress-algo=1, cipher-algo=aes256')
 631    </programlisting>
 632
 633    <para>
 634     All of the options except <literal>convert-crlf</literal> apply only to
 635     encrypt functions.  Decrypt functions get the parameters from the PGP
 636     data.
 637    </para>
 638
 639    <para>
 640     The most interesting options are probably
 641     <literal>compress-algo</literal> and <literal>unicode-mode</literal>.
 642     The rest should have reasonable defaults.
 643    </para>
 644
 645   <sect4>
 646    <title>cipher-algo</title>
 647
 648    <para>
 649     Which cipher algorithm to use.
 650    </para>
 651    <programlisting>
 652     Values: bf, aes128, aes192, aes256 (OpenSSL-only: <literal>3des</literal>, <literal>cast5</literal>)
 653     Default: aes128
 654     Applies to: pgp_sym_encrypt, pgp_pub_encrypt
 655    </programlisting>
 656   </sect4>
 657
 658   <sect4>
 659    <title>compress-algo</title>
 660
 661    <para>
 662     Which compression algorithm to use.  Only available if
 663     <productname>PostgreSQL</productname> was built with zlib.
 664    </para>
 665    <programlisting>
 666     Values:
 667       0 - no compression
 668       1 - ZIP compression
 669       2 - ZLIB compression (= ZIP plus meta-data and block CRCs)
 670     Default: 0
 671     Applies to: pgp_sym_encrypt, pgp_pub_encrypt
 672    </programlisting>
 673   </sect4>
 674
 675   <sect4>
 676    <title>compress-level</title>
 677
 678    <para>
 679     How much to compress.  Higher levels compress smaller but are slower.
 680     0 disables compression.
 681    </para>
 682    <programlisting>
 683     Values: 0, 1-9
 684     Default: 6
 685     Applies to: pgp_sym_encrypt, pgp_pub_encrypt
 686    </programlisting>
 687   </sect4>
 688
 689   <sect4>
 690    <title>convert-crlf</title>
 691
 692    <para>
 693     Whether to convert <literal>\n</literal> into <literal>\r\n</literal> when
 694     encrypting and <literal>\r\n</literal> to <literal>\n</literal> when
 695     decrypting.  RFC 4880 specifies that text data should be stored using
 696     <literal>\r\n</literal> line-feeds.  Use this to get fully RFC-compliant
 697     behavior.
 698    </para>
 699    <programlisting>
 700     Values: 0, 1
 701     Default: 0
 702     Applies to: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt
 703    </programlisting>
 704   </sect4>
 705
 706   <sect4>
 707    <title>disable-mdc</title>
 708
 709    <para>
 710     Do not protect data with SHA-1.  The only good reason to use this
 711     option is to achieve compatibility with ancient PGP products, predating
 712     the addition of SHA-1 protected packets to RFC 4880.
 713     Recent gnupg.org and pgp.com software supports it fine.
 714    </para>
 715    <programlisting>
 716     Values: 0, 1
 717     Default: 0
 718     Applies to: pgp_sym_encrypt, pgp_pub_encrypt
 719    </programlisting>
 720   </sect4>
 721
 722   <sect4>
 723    <title>enable-session-key</title>
 724
 725    <para>
 726     Use separate session key.  Public-key encryption always uses a separate
 727     session key; this is for symmetric-key encryption, which by default
 728     uses the S2K key directly.
 729    </para>
 730    <programlisting>
 731     Values: 0, 1
 732     Default: 0
 733     Applies to: pgp_sym_encrypt
 734    </programlisting>
 735   </sect4>
 736
 737   <sect4>
 738    <title>s2k-mode</title>
 739
 740    <para>
 741     Which S2K algorithm to use.
 742    </para>
 743    <programlisting>
 744     Values:
 745       0 - Without salt.  Dangerous!
 746       1 - With salt but with fixed iteration count.
 747       3 - Variable iteration count.
 748     Default: 3
 749     Applies to: pgp_sym_encrypt
 750    </programlisting>
 751   </sect4>
 752
 753   <sect4>
 754    <title>s2k-digest-algo</title>
 755
 756    <para>
 757     Which digest algorithm to use in S2K calculation.
 758    </para>
 759    <programlisting>
 760     Values: md5, sha1
 761     Default: sha1
 762     Applies to: pgp_sym_encrypt
 763    </programlisting>
 764   </sect4>
 765
 766   <sect4>
 767    <title>s2k-cipher-algo</title>
 768
 769    <para>
 770     Which cipher to use for encrypting separate session key.
 771    </para>
 772    <programlisting>
 773     Values: bf, aes, aes128, aes192, aes256
 774     Default: use cipher-algo
 775     Applies to: pgp_sym_encrypt
 776    </programlisting>
 777   </sect4>
 778
 779   <sect4>
 780    <title>unicode-mode</title>
 781
 782    <para>
 783     Whether to convert textual data from database internal encoding to
 784     UTF-8 and back.  If your database already is UTF-8, no conversion will
 785     be done, but the message will be tagged as UTF-8.  Without this option
 786     it will not be.
 787    </para>
 788    <programlisting>
 789     Values: 0, 1
 790     Default: 0
 791     Applies to: pgp_sym_encrypt, pgp_pub_encrypt
 792    </programlisting>
 793   </sect4>
 794   </sect3>
 795
 796  <sect3>
 797   <title>Generating PGP keys with GnuPG</title>
 798
 799   <para>
 800    To generate a new key:
 801   </para>
 802   <programlisting>
 803    gpg --gen-key
 804   </programlisting>
 805   <para>
 806    The preferred key type is <quote>DSA and Elgamal</>.
 807   </para>
 808   <para>
 809    For RSA encryption you must create either DSA or RSA sign-only key
 810    as master and then add an RSA encryption subkey with
 811    <literal>gpg --edit-key</literal>.
 812   </para>
 813   <para>
 814    To list keys:
 815   </para>
 816   <programlisting>
 817    gpg --list-secret-keys
 818   </programlisting>
 819   <para>
 820    To export a public key in ascii-armor format:
 821   </para>
 822   <programlisting>
 823    gpg -a --export KEYID > public.key
 824   </programlisting>
 825   <para>
 826    To export a secret key in ascii-armor format:
 827   </para>
 828   <programlisting>
 829    gpg -a --export-secret-keys KEYID > secret.key
 830   </programlisting>
 831   <para>
 832    You need to use <function>dearmor()</> on these keys before giving them to
 833    the PGP functions.  Or if you can handle binary data, you can drop
 834    <literal>-a</literal> from the command.
 835   </para>
 836   <para>
 837    For more details see <literal>man gpg</literal>,
 838    <ulink url="http://www.gnupg.org/gph/en/manual.html">The GNU
 839    Privacy Handbook</ulink> and other documentation on
 840    <ulink url="http://www.gnupg.org"></ulink>.
 841   </para>
 842  </sect3>
 843
 844  <sect3>
 845   <title>Limitations of PGP code</title>
 846
 847   <itemizedlist>
 848    <listitem>
 849     <para>
 850     No support for signing.  That also means that it is not checked
 851     whether the encryption subkey belongs to the master key.
 852     </para>
 853    </listitem>
 854    <listitem>
 855     <para>
 856     No support for encryption key as master key.  As such practice
 857     is generally discouraged, this should not be a problem.
 858     </para>
 859    </listitem>
 860    <listitem>
 861     <para>
 862     No support for several subkeys.  This may seem like a problem, as this
 863     is common practice.  On the other hand, you should not use your regular
 864     GPG/PGP keys with <filename>pgcrypto</>, but create new ones,
 865     as the usage scenario is rather different.
 866     </para>
 867    </listitem>
 868   </itemizedlist>
 869   </sect3>
 870  </sect2>
 871
 872  <sect2>
 873   <title>Raw encryption functions</title>
 874
 875   <para>
 876    These functions only run a cipher over data; they don't have any advanced
 877    features of PGP encryption.  Therefore they have some major problems:
 878   </para>
 879   <orderedlist>
 880    <listitem>
 881     <para>
 882     They use user key directly as cipher key.
 883     </para>
 884    </listitem>
 885    <listitem>
 886     <para>
 887     They don't provide any integrity checking, to see
 888     if the encrypted data was modified.
 889     </para>
 890    </listitem>
 891    <listitem>
 892     <para>
 893     They expect that users manage all encryption parameters
 894     themselves, even IV.
 895     </para>
 896    </listitem>
 897    <listitem>
 898     <para>
 899     They don't handle text.
 900     </para>
 901    </listitem>
 902   </orderedlist>
 903   <para>
 904    So, with the introduction of PGP encryption, usage of raw
 905    encryption functions is discouraged.
 906   </para>
 907
 908   <synopsis>
 909     encrypt(data bytea, key bytea, type text) returns bytea
 910     decrypt(data bytea, key bytea, type text) returns bytea
 911
 912     encrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
 913     decrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
 914   </synopsis>
 915
 916   <para>
 917    Encrypt/decrypt data using the cipher method specified by
 918    <parameter>type</parameter>.  The syntax of the
 919    <parameter>type</parameter> string is:
 920   </para>
 921
 922   <synopsis>
 923    <replaceable>algorithm</> <optional> <literal>-</> <replaceable>mode</> </optional> <optional> <literal>/pad:</> <replaceable>padding</> </optional>
 924   </synopsis>
 925
 926   <para>
 927    where <replaceable>algorithm</> is one of:
 928   </para>
 929   <itemizedlist>
 930    <listitem><para><literal>bf</literal> &mdash; Blowfish</para></listitem>
 931    <listitem><para><literal>aes</literal> &mdash; AES (Rijndael-128)</para></listitem>
 932   </itemizedlist>
 933   <para>
 934    and <replaceable>mode</> is one of:
 935   </para>
 936   <itemizedlist>
 937    <listitem>
 938     <para>
 939     <literal>cbc</literal> &mdash; next block depends on previous (default)
 940     </para>
 941    </listitem>
 942    <listitem>
 943     <para>
 944     <literal>ecb</literal> &mdash; each block is encrypted separately (for
 945     testing only)
 946     </para>
 947    </listitem>
 948   </itemizedlist>
 949   <para>
 950    and <replaceable>padding</> is one of:
 951   </para>
 952   <itemizedlist>
 953    <listitem>
 954     <para>
 955     <literal>pkcs</literal> &mdash; data may be any length (default)
 956     </para>
 957    </listitem>
 958    <listitem>
 959     <para>
 960     <literal>none</literal> &mdash; data must be multiple of cipher block size
 961     </para>
 962    </listitem>
 963   </itemizedlist>
 964   <para>
 965    So, for example, these are equivalent:
 966   </para>
 967   <programlisting>
 968    encrypt(data, 'fooz', 'bf')
 969    encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
 970   </programlisting>
 971   <para>
 972    In <function>encrypt_iv</> and <function>decrypt_iv</>, the
 973    <parameter>iv</> parameter is the initial value for the CBC mode;
 974    it is ignored for ECB.
 975    It is clipped or padded with zeroes if not exactly block size.
 976    It defaults to all zeroes in the functions without this parameter.
 977   </para>
 978  </sect2>
 979
 980  <sect2>
 981   <title>Random-data functions</title>
 982
 983   <synopsis>
 984    gen_random_bytes(count integer) returns bytea
 985   </synopsis>
 986   <para>
 987    Returns <parameter>count</> cryptographically strong random bytes.
 988    At most 1024 bytes can be extracted at a time.  This is to avoid
 989    draining the randomness generator pool.
 990   </para>
 991  </sect2>
 992
 993  <sect2>
 994   <title>Notes</title>
 995
 996   <sect3>
 997    <title>Configuration</title>
 998
 999    <para>
1000     <filename>pgcrypto</> configures itself according to the findings of the
1001     main PostgreSQL <literal>configure</literal> script.  The options that
1002     affect it are <literal>--with-zlib</literal> and
1003     <literal>--with-openssl</literal>.
1004    </para>
1005
1006    <para>
1007     When compiled with zlib, PGP encryption functions are able to
1008     compress data before encrypting.
1009    </para>
1010
1011    <para>
1012     When compiled with OpenSSL, there will be more algorithms available.
1013     Also public-key encryption functions will be faster as OpenSSL
1014     has more optimized BIGNUM functions.
1015    </para>
1016
1017    <table id="pgcrypto-with-without-openssl">
1018     <title>Summary of functionality with and without OpenSSL</title>
1019     <tgroup cols="3">
1020      <thead>
1021       <row>
1022        <entry>Functionality</entry>
1023        <entry>Built-in</entry>
1024        <entry>With OpenSSL</entry>
1025       </row>
1026      </thead>
1027      <tbody>
1028       <row>
1029        <entry>MD5</entry>
1030        <entry>yes</entry>
1031        <entry>yes</entry>
1032       </row>
1033       <row>
1034        <entry>SHA1</entry>
1035        <entry>yes</entry>
1036        <entry>yes</entry>
1037       </row>
1038       <row>
1039        <entry>SHA224/256/384/512</entry>
1040        <entry>yes</entry>
1041        <entry>yes (Note 1)</entry>
1042       </row>
1043       <row>
1044        <entry>Other digest algorithms</entry>
1045        <entry>no</entry>
1046        <entry>yes (Note 2)</entry>
1047       </row>
1048       <row>
1049        <entry>Blowfish</entry>
1050        <entry>yes</entry>
1051        <entry>yes</entry>
1052       </row>
1053       <row>
1054        <entry>AES</entry>
1055        <entry>yes</entry>
1056        <entry>yes (Note 3)</entry>
1057       </row>
1058       <row>
1059        <entry>DES/3DES/CAST5</entry>
1060        <entry>no</entry>
1061        <entry>yes</entry>
1062       </row>
1063       <row>
1064        <entry>Raw encryption</entry>
1065        <entry>yes</entry>
1066        <entry>yes</entry>
1067       </row>
1068       <row>
1069        <entry>PGP Symmetric encryption</entry>
1070        <entry>yes</entry>
1071        <entry>yes</entry>
1072       </row>
1073       <row>
1074        <entry>PGP Public-Key encryption</entry>
1075        <entry>yes</entry>
1076        <entry>yes</entry>
1077       </row>
1078      </tbody>
1079     </tgroup>
1080    </table>
1081
1082    <para>
1083     Notes:
1084    </para>
1085
1086    <orderedlist>
1087     <listitem>
1088      <para>
1089       SHA2 algorithms were added to OpenSSL in version 0.9.8.  For
1090       older versions, <filename>pgcrypto</> will use built-in code.
1091      </para>
1092     </listitem>
1093     <listitem>
1094      <para>
1095       Any digest algorithm OpenSSL supports is automatically picked up.
1096       This is not possible with ciphers, which need to be supported
1097       explicitly.
1098      </para>
1099     </listitem>
1100     <listitem>
1101      <para>
1102       AES is included in OpenSSL since version 0.9.7.  For
1103       older versions, <filename>pgcrypto</> will use built-in code.
1104      </para>
1105     </listitem>
1106    </orderedlist>
1107   </sect3>
1108
1109   <sect3>
1110    <title>NULL handling</title>
1111
1112    <para>
1113     As is standard in SQL, all functions return NULL, if any of the arguments
1114     are NULL.  This may create security risks on careless usage.
1115    </para>
1116   </sect3>
1117
1118   <sect3>
1119    <title>Security limitations</title>
1120
1121    <para>
1122     All <filename>pgcrypto</> functions run inside the database server.
1123     That means that all
1124     the data and passwords move between <filename>pgcrypto</> and client
1125     applications in clear text.  Thus you must:
1126    </para>
1127
1128    <orderedlist>
1129     <listitem>
1130      <para>Connect locally or use SSL connections.</para>
1131     </listitem>
1132     <listitem>
1133      <para>Trust both system and database administrator.</para>
1134     </listitem>
1135    </orderedlist>
1136
1137    <para>
1138     If you cannot, then better do crypto inside client application.
1139    </para>
1140   </sect3>
1141
1142   <sect3>
1143    <title>Useful reading</title>
1144
1145    <itemizedlist>
1146     <listitem>
1147      <para><ulink url="http://www.gnupg.org/gph/en/manual.html"></ulink></para>
1148      <para>The GNU Privacy Handbook.</para>
1149     </listitem>
1150     <listitem>
1151      <para><ulink url="http://www.openwall.com/crypt/"></ulink></para>
1152      <para>Describes the crypt-blowfish algorithm.</para>
1153     </listitem>
1154     <listitem>
1155      <para>
1156       <ulink url="http://www.stack.nl/~galactus/remailers/passphrase-faq.html"></ulink>
1157      </para>
1158      <para>How to choose a good password.</para>
1159     </listitem>
1160     <listitem>
1161      <para><ulink url="http://world.std.com/~reinhold/diceware.html"></ulink></para>
1162      <para>Interesting idea for picking passwords.</para>
1163     </listitem>
1164     <listitem>
1165      <para>
1166       <ulink url="http://www.interhack.net/people/cmcurtin/snake-oil-faq.html"></ulink>
1167      </para>
1168      <para>Describes good and bad cryptography.</para>
1169     </listitem>
1170    </itemizedlist>
1171   </sect3>
1172
1173   <sect3>
1174    <title>Technical references</title>
1175
1176    <itemizedlist>
1177     <listitem>
1178      <para><ulink url="http://www.ietf.org/rfc/rfc4880.txt"></ulink></para>
1179      <para>OpenPGP message format.</para>
1180     </listitem>
1181     <listitem>
1182      <para><ulink url="http://www.ietf.org/rfc/rfc1321.txt"></ulink></para>
1183      <para>The MD5 Message-Digest Algorithm.</para>
1184     </listitem>
1185     <listitem>
1186      <para><ulink url="http://www.ietf.org/rfc/rfc2104.txt"></ulink></para>
1187      <para>HMAC: Keyed-Hashing for Message Authentication.</para>
1188     </listitem>
1189     <listitem>
1190      <para>
1191       <ulink url="http://www.usenix.org/events/usenix99/provos.html"></ulink>
1192      </para>
1193      <para>Comparison of crypt-des, crypt-md5 and bcrypt algorithms.</para>
1194     </listitem>
1195     <listitem>
1196      <para><ulink url="http://csrc.nist.gov/cryptval/des.htm"></ulink></para>
1197      <para>Standards for DES, 3DES and AES.</para>
1198     </listitem>
1199     <listitem>
1200      <para>
1201       <ulink url="http://en.wikipedia.org/wiki/Fortuna_(PRNG)"></ulink>
1202      </para>
1203      <para>Description of Fortuna CSPRNG.</para>
1204     </listitem>
1205     <listitem>
1206      <para><ulink url="http://jlcooke.ca/random/"></ulink></para>
1207      <para>Jean-Luc Cooke Fortuna-based /dev/random driver for Linux.</para>
1208     </listitem>
1209     <listitem>
1210      <para><ulink url="http://www.cs.ut.ee/~helger/crypto/"></ulink></para>
1211      <para>Collection of cryptology pointers.</para>
1212     </listitem>
1213    </itemizedlist>
1214   </sect3>
1215  </sect2>
1216
1217  <sect2>
1218   <title>Author</title>
1219
1220   <para>
1221    Marko Kreen <email>markokr@gmail.com</email>
1222   </para>
1223
1224   <para>
1225    <filename>pgcrypto</filename> uses code from the following sources:
1226   </para>
1227
1228   <informaltable>
1229    <tgroup cols="3">
1230     <thead>
1231      <row>
1232       <entry>Algorithm</entry>
1233       <entry>Author</entry>
1234       <entry>Source origin</entry>
1235      </row>
1236     </thead>
1237     <tbody>
1238      <row>
1239       <entry>DES crypt</entry>
1240       <entry>David Burren and others</entry>
1241       <entry>FreeBSD libcrypt</entry>
1242      </row>
1243      <row>
1244       <entry>MD5 crypt</entry>
1245       <entry>Poul-Henning Kamp</entry>
1246       <entry>FreeBSD libcrypt</entry>
1247      </row>
1248      <row>
1249       <entry>Blowfish crypt</entry>
1250       <entry>Solar Designer</entry>
1251       <entry>www.openwall.com</entry>
1252      </row>
1253      <row>
1254       <entry>Blowfish cipher</entry>
1255       <entry>Simon Tatham</entry>
1256       <entry>PuTTY</entry>
1257      </row>
1258      <row>
1259       <entry>Rijndael cipher</entry>
1260       <entry>Brian Gladman</entry>
1261       <entry>OpenBSD sys/crypto</entry>
1262      </row>
1263      <row>
1264       <entry>MD5 and SHA1</entry>
1265       <entry>WIDE Project</entry>
1266       <entry>KAME kame/sys/crypto</entry>
1267      </row>
1268      <row>
1269       <entry>SHA256/384/512 </entry>
1270       <entry>Aaron D. Gifford</entry>
1271       <entry>OpenBSD sys/crypto</entry>
1272      </row>
1273      <row>
1274       <entry>BIGNUM math</entry>
1275       <entry>Michael J. Fromberger</entry>
1276       <entry>dartmouth.edu/~sting/sw/imath</entry>
1277      </row>
1278     </tbody>
1279    </tgroup>
1280   </informaltable>
1281  </sect2>
1282
1283 </sect1>