[patch 3/3] new documentation - Mailing list pgsql-patches

- reformat in asciidoc syntax
- clarify various parts
- add high-level description of PGP structure
- add a comparison of crypt vs. regular hashes


Index: pgsql/contrib/pgcrypto/README.pgcrypto
===================================================================
*** pgsql.orig/contrib/pgcrypto/README.pgcrypto
--- pgsql/contrib/pgcrypto/README.pgcrypto
***************
*** 1,362 ****

! pgcrypto 0.4 - cryptographic functions for PostgreSQL.
! ======================================================
! by Marko Kreen <marko@l-t.ee>


! INSTALLATION
! ============

! Edit makefile, if you want to use any external library.

! NB!  Default randomness source is libc random() function.  This
! is so only to get pgcrypto build everywhere.  Randomness is
! needed for gen_salt() and pgp_encrypt() functions.  So if you plan
! using those, you should definitely change that by editing Makefile.
! You can should use urandom device if your OS supports it, otherwise
! link pgcrypto against OpenSSL library and use its PRNG.

! After editing Makefile:

- make
- make install

! To run regression tests, install both PostgreSQL and pgcrypto
! and then run

! make installcheck

! SQL FUNCTIONS
! =============

!     If any of arguments are NULL they return NULL.

! digest(data::bytea, type::text)::bytea

!     Type is here the algorithm to use. E.g. 'md5', 'sha1', ...
!     Returns binary hash.

! digest_exists(type::text)::bool

!     Returns BOOL whether given hash exists.

! hmac(data::bytea, key::bytea, type::text)::bytea

-     Calculates Hashed MAC over data.  type is the same as
-     in digest().  Returns binary hash.  Similar to digest()
-     but noone can alter data and re-calculate hash without
-     knowing key.  If the key is larger than hash blocksize
-     it will first hashed and the hash will be used as key.
-
-     [ HMAC is described in RFC2104. ]

! hmac_exists(type::text)::bool
!     Returns BOOL.  It is separate function because all hashes
!     cannot be used in HMAC.

! crypt(password::text, salt::text)::text

-     Calculates UN*X crypt(3) style hash.  Useful for storing
-     passwords.  For generating salt you should use the
-     gen_salt() function.  Usage:

!     New password:
!
!       UPDATE .. SET pswhash = crypt(new_psw, gen_salt('md5'));
!
!     Authentication:

!       SELECT pswhash = crypt(given_psw, pswhash) WHERE .. ;
!
!     returns BOOL whether the given_psw is correct.  DES crypt
!     has max key of 8 bytes, MD5 has max key at least 2^32-1
!     bytes but may be larger on some platforms...

-     Builtin crypt() supports DES, Extended DES, MD5 and Blowfish
-     (variant 2a) algorithms.

! gen_salt(type::text)::text

!     Generates a new random salt for usage in crypt().  Type
!
!     'des'    - Old UNIX, not recommended
!     'md5'    - md5-based crypt()
!     'xdes'    - 'Extended DES'
!     'bf'    - Blowfish-based, variant 2a

!     When you use --enable-system-crypt then note that system
!     libcrypt may not support them all.

! gen_salt(type::text, rounds::int4)::text

-     same as above, but lets user specify iteration count
-     for algorithm.  Number is algorithm specific:

!     type    default    min    max
!     ---------------------------------
!     xdes    725    1    16777215
!     bf    6    4    31

!     In case of xdes there is a additional limitation that the
!     count must be a odd number.

!     The higher the count, the more time it takes to calculate
!     crypt and therefore the more time to break it.  But beware!
!     With too high count it takes a _very_long_ time to
!     calculate it.

!     For maximum security, you should choose the 'bf' crypt
!     and use maximum number of rounds you can still tolerate.

! armor(bytea)::text
! dearmor(text)::bytea

!     Those wrap/unwrap data into PGP Ascii Armor which
!     is basically Base64 with CRC and additional formatting.

! pgp_sym_encrypt(data::text, key::text)::bytea
! pgp_sym_encrypt(data::text, key::text, arg::text)::bytea
! pgp_sym_encrypt_bytea(data::bytea, key::text)::bytea
! pgp_sym_encrypt_bytea(data::bytea, key::text, arg::text)::bytea

- pgp_sym_decrypt(data::bytea, key::text)::text
- pgp_sym_decrypt(data::bytea, key::text, arg::text)::text
- pgp_sym_decrypt_bytea(data::text, key::text)::bytea
- pgp_sym_decrypt_bytea(data::text, key::text, arg::text)::bytea

!     Encrypt data into OpenPGP Symmetrically Encrypted Data
!     message.  And decrypt it from it.

!     Note that the pgp_sym_encrypt_bytea functions tag the data
!     as binary, as the pgp_sym_encrypt will tag the data as text.
!     You can not decrypt the binary data as text.  But you can
!     decrypt text data as binary.  This rule avoids having
!     broken textual data in PostgreSQL.

!     Both encrypt and decrypt accept also third argument, which
!     is parameters to the function in following format:
!
!       parm=val[,parm=val]...
!
!     Example:

!       select pgp_sym_encrypt('data', 'psw',
!             'compress-algo=2, unicode-mode=1');

!     Accepted parameters are:

-     cipher-algo: bf, aes, aes128, aes192, aes256
-       Cipher algorithm to use.  OpenSSL gives additional algorithms:
-       3des, cast5
-       Default: aes128
-
-     compress-algo: 0, 1, 2
-       Which compression algorithm to use.
-         0 - no compression
-         1 - ZIP compression
-         2 - ZLIB compression [=ZIP plus meta-data and block-CRC's]
-       Default: 0

-     compress-level: 0, 1-9
-       How much to compress.  Bigger level compresses smaller
-       but also slower.  0 disables compression.
-       Default: 6

!     convert-crlf: 0, 1
!       Whether to convert \n into \r\n when encrypting and
!       \r\n to \n when decrypting.  RFC2440 specifies that
!       text packets should use "\r\n" line-feeds.
!       Use this to get fully RFC-compliant behaviour.
!       Default: 0

!     disable-mdc: 0, 1
!       Do not protect data with SHA-1.  Note that SHA-1 protected
!       packet is from upcoming update to RFC2440.  (Currently at
!       version RFC2440bis-13.)  You need to disable it if you need
!       compatibility with ancient PGP products.  Recent gnupg.org
!       and pgp.com software supports it fine.
!       Default: 0
!
!     enable-session-key: 0, 1
!       Use separate session key.
!       Default: 0
!
!     s2k-mode: 0, 1, 3
!       Which S2K algorithm to use.  0 is dangerous - without salt.
!       Default: 3
!
!     s2k-digest-algo: md5, sha1
!       Which digest algorithm to use in S2K calculation.
!       Default: SHA-1

!     s2k-cipher-algo: bf, aes, aes128, aes192, aes256
!       Which cipher to use for encrypting separate session key.
!       Default: same as cipher-algo.

!     unicode-mode: 0, 1
!       Whether to convert textual data from database internal
!       encoding to UTF-8 and back.
!       Default: 0

!     Only 'convert-crlf' applies to both encrypt and decrypt,
!     all others apply only to encrypt - decrypt gets the
!     settings from PGP data.
!
!
! pgp_pub_encrypt(data::text, key::bytea)::bytea
! pgp_pub_encrypt(data::text, key::bytea, arg::text)::bytea
! pgp_pub_encrypt_bytea(data::bytea, bytea::text)::bytea
! pgp_pub_encrypt_bytea(data::bytea, bytea::text, arg::text)::bytea

- pgp_pub_decrypt(data::bytea, key::bytea)::text
- pgp_pub_decrypt(data::bytea, key::bytea, psw::text)::text
- pgp_pub_decrypt(data::bytea, key::bytea, psw::text, arg::text)::text
- pgp_pub_decrypt_bytea(data::text, key::bytea)::bytea
- pgp_pub_decrypt_bytea(data::text, key::bytea, psw::text)::bytea
- pgp_pub_decrypt_bytea(data::text, key::bytea, psw::text, arg::bytea)::bytea

!     Encrypt data into OpenPGP Public-Key Encrypted Data
!     message.  And decrypt it from it.  The arg parameter is
!     described in pgp_sym_* section.

!     The key must be a public-key packet for pgp_pub_encrypt
!     functions and a secret key packet for pgp_pub_decrypt
!     functions.  Trying to encrypt with secret key gives a error.
!     While being technically possible, it is probably a sign of
!     user error and leaking secret keys.

!     Here is a example how to generate them:
!
!     Generate a new key:
!
!       gpg --gen-key
!
!     You need to pick "DSA and Elgamal" key type, others
!     are sign-only.

!     List keys:
!
!       gpg --list-secret-keys

!     Export ascii-armored public key:

!       gpg -a --export KEYID > public.key
!
!     Export ascii-armored secret key:

!       gpg -a --export-secret-keys KEYID > secret.key

!     You need to use dearmor() on them before giving giving
!     them to pgp_pub_* functions.  Ofcourse, if you can handle
!     binary data, you can drop "-a" from gpg.


! pgp_key_id(key / data)

!     It shows you either key ID if given PGP public or secret
!     key.  Or it gives the key ID what was used for encrypting
!     the data, if given encrypted data.

!     It can return 2 special key ID's:

!       SYMKEY - it got symmetrically encrypted data.
!       ANYKEY - the data packet key ID is clear.  That means
!            you should try all you secret keys on it.

- encrypt(data::bytea, key::bytea, type::text)::bytea
- decrypt(data::bytea, key::bytea, type::text)::bytea
- encrypt_iv(data::bytea, key::bytea, iv::bytea, type::text)::bytea
- decrypt_iv(data::bytea, key::bytea, iv::bytea, type::text)::bytea

!     Encrypt/decrypt data with cipher, padding data if needed.

!     Pseudo-noteup:

!     algo ['-' mode] ['/pad:' padding]

!     Supported algorithms:
!
!         bf        - Blowfish
!         aes, rijndael    - Rijndael-128

!     Others depend on library and are not tested enough, so
!     play on your own risk.

!     Modes: 'cbc' (default), 'ecb'.  Again, library may support
!     more.

!     Padding is 'pkcs' (default), 'none'.  'none' is mostly for
!     testing ciphers, you should not need it.

!     So, example:

-         encrypt(data, 'fooz', 'bf')
-
-     is equal to

!         encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')

!     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.


! ALGORITHMS
! ==========

! The standard functionality at the moment consists of

! Hashes: md5, sha1
! Ciphers: bf, aes
! Modes: cbc, ecb

- TODO: write standard names for optional ciphers too.

! LIBRARIES
! =========

! * crypt()

-     internal: des, xdes, md5, bf

!     -lcrypt: ??? (whatever you have)

! * other:

! [ This only lists stuff that the libraries claim to support.  So
!   pgcrypto may work with all of them.  But ATM tested are only the
!   standard ciphers.  On others pgcrypto and library may mess something
!   up. You have been warned.  ]

! internal (default):
!     Hashes: MD5, SHA1
!     Ciphers: Blowfish, Rijndael-128


! OpenSSL (0.9.7):
!     Hashes:    MD5, SHA1, RIPEMD160, MD2
!     Ciphers:    Blowfish, AES, CAST5, DES, 3DES
!     License:    BSD-like with strong advertisement
!     Url:    http://www.openssl.org/


! CREDITS
! =======

  I have used code from following sources:

! DES crypt() by David Burren and others    FreeBSD libcrypt
! MD5 crypt() by Poul-Henning Kamp    FreeBSD libcrypt
! Blowfish crypt() by Solar Designer    www.openwall.com
! Blowfish cipher by Niels Provos        OpenBSD sys/crypto
! Rijndael cipher by Brian Gladman    OpenBSD sys/crypto
! MD5 and SHA1 by WIDE Project        KAME kame/sys/crypto

- LEGALESE
- ========

! * I owe a beer to Poul-Henning.

  * This product includes software developed by Niels Provos.


--- 1,675 ----

! pgcrypto - cryptographic functions for PostgreSQL
! =================================================
! Marko Kreen <marko@l-t.ee>


! 1.  Installation
! -----------------

! Run following commands:

!     make
!     make install
!     make installcheck

! The `make installcheck` command is important.  It runs regression tests
! for the module.  They make sure the functions here produce correct
! results.


! 2.  Notes
! ----------

! 2.1.  Configuration
! ~~~~~~~~~~~~~~~~~~~~

! pgcrypto configures itself according to the findings of main PostgreSQL
! `configure` script.  The options that affect it are `--with-zlib` and
! `--with-openssl`.

! Without zlib, the PGP functions will not support compressed data inside
! PGP encrypted packets.

! Without OpenSSL public-key encryption does not work, as pgcrypto does
! not contain yet math functions for large integers.

! There are some other differences between with and without OpenSSL build:

! `----------------------------`---------`------------
!  Functionality                built-in   OpenSSL
! ----------------------------------------------------
!  MD5                          yes       yes
!  SHA1                         yes       yes
!  SHA256/384/512               yes       since 0.9.8
!  Any other digest algo        no        yes (1)
!  Blowfish                     yes       yes
!  AES                          yes       yes (2)
!  DES/3DES/CAST5               no        yes
!  Raw encryption               yes       yes
!  PGP Symmetric encryption     yes       yes
!  PGP Public-Key encryption    no        yes
! ----------------------------------------------------

! 1. Any digest algorithm OpenSSL supports is automatically picked up.
!    This is not possible with ciphers, which need to be supported
!    explicitly.

! 2. 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.


! 2.2.  NULL handling
! ~~~~~~~~~~~~~~~~~~~~

! As standard in SQL, all functions return NULL, if any of it's arguments
! are NULL.  This may create security risks on careless usage.


! 2.3.  Deprecated functions
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~

! The `digest_exists()`, `hmac_exists()` and `cipher_exists()` functions
! are deprecated.  The plan is to remove those in PostgreSQL 8.2.


! 2.4.  Security
! ~~~~~~~~~~~~~~~

! 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:

! 1.  Connect locally or use SSL connections.
! 2.  Trust both system and database administrator.

! If you cannot, then better do crypto inside client application.


! 3.  General hashing
! --------------------

! 3.1.  digest(data, type)
! ~~~~~~~~~~~~~~~~~~~~~~~~~

!   digest(data text, type text) RETURNS bytea
!   digest(data bytea, type text) RETURNS bytea

! Type is here the algorithm to use.  Standard algorithms are `md5` and
! `sha1`, although there may be more supported, depending on build
! options.

! Returns binary hash.

! If you want hexadecimal string, use `encode()` on result.  Example:

!     CREATE OR REPLACE FUNCTION sha1(bytea) RETURNS text AS $$
!       SELECT encode(digest($1, 'sha1'), 'hex')
!     $$ LANGUAGE SQL STRICT IMMUTABLE;


! 3.2.  hmac(data, key, type)
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

!   hmac(data text, key text, type text) RETURNS bytea
!   hmac(data bytea, key text, type text) RETURNS bytea

! 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.

! 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.

! Returns binary hash.



! 4.  Password hashing
! ---------------------

! The functions `crypt()` and `gen_salt()` are specifically designed
! for hashing passwords.  `crypt()` does the hashing and `gen_salt()`
! prepares algorithm parameters for it.

! The algorithms in `crypt()` differ from usual hashing algorithms like
! MD5 or SHA1 in following respects:

! 1. They are slow.  As the amount of data is so small, this is only
!    way to make brute-forcing passwords hard.
! 2. Include random 'salt' with result, so that users having same
!    password would have different crypted passwords.  This also
!    additional defense against reversing the algorithm.
! 3. Include algorithm type in the result, so passwords hashed with
!    different algorithms can co-exist.
! 4. Some of them are adaptive - that means after computers get
!    faster, you can tune the algorithm to be slower, without
!    introducing incompatibility with existing passwords.

! Supported algorithms:
! `------`-------------`---------`----------`---------------------------
!  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
! ----------------------------------------------------------------------


! 4.1.  crypt(password, salt)
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

!   crypt(password text, salt text) RETURNS text

! 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.

! Example - setting new password:

!     UPDATE .. SET pswhash = crypt('new password', gen_salt('md5'));

! Example - authentication:

!     SELECT pswhash = crypt('entered password', pswhash) WHERE .. ;

! returns true or false whether the entered password is correct.
! It also can return NULL if `pswhash` field is NULL.


! 4.2.  gen_salt(type)
! ~~~~~~~~~~~~~~~~~~~~~

!   gen_salt(type text) RETURNS text

! Generates a new random salt for usage in `crypt()`.  For adaptible
! algorithms, it uses the default iteration count.

! Accepted types are: `des`, `xdes`, `md5` and `bf`.


! 4.3.  gen_salt(type, rounds)
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

!   gen_salt(type text, rounds integer) RETURNS text

! Same as above, but lets user specify iteration count for some
! algorithms.  The higher the count, the more time it takes to hash
! ti password and therefore the more time to break it.  Although with
! too high count the time to calculate a hash may be several years
! - which is somewhat impractical.

! Number is algorithm specific:

! `-----'---------'-----'----------
!  type   default   min   max
! ---------------------------------
!  `xdes`     725     1   16777215
!  `bf`         6     4         31
! ---------------------------------

! In case of xdes there is a additional limitation that the count must be
! a odd number.

! Notes:

! - Original DES crypt was designed to have the speed of 4 hashes per
!   second on the hardware that time.
! - Slower that 4 hashes per second would probably damper usability.
! - Faster that 100 hashes per second is probably too fast.
! - See next section about possible values for `crypt-bf`.


! 4.4.  Comparison of crypt and regular hashes
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

! Here is a table that should give overview of relative slowness
! of different hashing algorithms.

+ * The goal is to crack a 8-character password, which consists:
+   1.  Only from lowercase letters
+   2.  Numbers, lower- and uppercase letters.
+ * The table below shows how much time it would take to try all
+   combinations of characters.
+ * The `crypt-bf` is featured in several settings - the number
+   after slash is the `rounds` parameter of `gen_salt()`.

! `------------'----------'--------------'--------------------
! 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
! password       143781000       25 mins              18 days
! ------------------------------------------------------------

! * The machine used is 1.5GHz Pentium 4.
! * crypt-des and crypt-md5 algorithm numbers are taken from
!   John the Ripper v1.6.38 `-test` output.
! * MD5 numbers are from mdcrack 1.2.
! * SHA1 numbers are from lcrack-20031130-beta.
! * MySQL password() numbers are from my own tests.
!   (http://grue.l-t.ee/~marko/src/mypass/)
! * `crypt-bf` 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: `john -test` shows 213
!   loops/sec for crypt-bf/5.  (The small difference in results is in
!   accordance to the fact that the `crypt-bf` implementation in pgcrypto
!   is same one that is used in John the Ripper.)

! Note that the "try all combinations" 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 will be cracked much faster than the above
! numbers suggest, and a 6-character non-word like password may escape
! cracking.  Or may not.


! 5.  PGP encryption
! -------------------

! The functions here implement the encryption part of OpenPGP (RFC2440)
! standard.


! 5.1.  Overview
! ~~~~~~~~~~~~~~~

! Encrypted PGP message consists of 2 packets:

! - Packet for session key - either symmetric- or public-key encrypted.
! - Packet for session-key encrypted data.

! When encrypting with password:

+ 1. Given password is hashed using String2Key (S2K) algorithm.  This
+    is rather similar to `crypt()` algorithm - purposefully slow
+    and with random salt - but is produces a full-length binary key.
+ 2. If separate session key is requested, new random key will be
+    generated.  Otherwise S2K key will be used directly as session key.
+ 3. 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.

! When encrypting with public key:

+ 1. New random session key is generated.
+ 2. It is encrypted using public key and put into session key packet.

! Now common part, the session-key encrypted data packet:
!
! 1. Optional data-manipulation: compression, conversion to UTF-8,
!    conversion of line-endings.
! 2. Data is prefixed with block of random bytes.  This is equal
!    to using random IV.
! 3. A SHA1 hash of random prefix and data is appended.
! 4. All this is encrypted with session key.
!
!
! 5.2.  pgp_sym_encrypt(data, psw)
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!
!   pgp_sym_encrypt(data text, psw text [, options text] ) RETURNS bytea
!   pgp_sym_encrypt_bytea(data bytea, psw text [, options text] ) RETURNS bytea
!
! Return a symmetric-key encrypted PGP message.
!
! Options are described in section 5.7.
!
!
! 5.3. pgp_sym_decrypt(msg, psw)
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!
!   pgp_sym_decrypt(msg bytea, psw text [, options text] ) RETURNS text
!   pgp_sym_decrypt_bytea(msg bytea, psw text [, options text] ) RETURNS bytea
!
! Decrypt a symmetric-key encrypted PGP message.
!
! Options are described in section 5.7.
!
!
! 5.4.  pgp_pub_encrypt(data, pub_key)
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!
!   pgp_pub_encrypt(data text, key bytea [, options text] ) RETURNS bytea
!   pgp_pub_encrypt_bytea(data bytea, key bytea [, options text] ) RETURNS bytea
!
! Encrypt data with a public key.  Giving this function a secret key will
! produce a error.
!
! Options are described in section 5.7.
!
!
! 5.5.  pgp_pub_decrypt(msg, sec_key [, psw])
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!
!   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
!
! 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.
!
! Options are described in section 5.7.
!
!
! 5.6.  pgp_key_id(key / msg)
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!
!   pgp_key_id(key or msg bytea) RETURNS text
!
! It shows you either key ID if given PGP public or secret key.  Or it
! gives the key ID what was used for encrypting the data, if given
! encrypted message.
!
! It can return 2 special key ID's:
!
! SYMKEY::
!    The data is encrypted with symmetric key.
!
! ANYKEY::
!    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.
!
! 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.
!
!
! 5.7.  armor / dearmor
! ~~~~~~~~~~~~~~~~~~~~~~
!
!   armor(data bytea) RETURNS text
!   dearmor(data text) RETURNS bytea
!
! Those wrap/unwrap data into PGP Ascii Armor which is basically Base64
! with CRC and additional formatting.
!
!
! 5.8.  Options for PGP functions
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!
! Option are named to be similar to GnuPG.  Values should be given after
! equal sign, different options from each other with commas.  Example:
!
!   pgp_sym_encrypt(data, psw, 'compress-also=1, cipher-algo=aes256')
!
! All of the options except `convert-crlf` apply only to encrypt
! functions.  Decrypt functions get the parameters from PGP data.
!
! Most interesting options are probably `compression-algo` and
! `unicode-mode`.  The rest should have reasonable defaults.
!
!
! cipher-algo::
!   What cipher algorithm to use.
!
!   Values: bf, aes128, aes192, aes256 (OpenSSL-only: `3des`, `cast5`)
!   Default: aes128
!   Applies: pgp_sym_encrypt, pgp_pub_encrypt
!
!
! compress-algo::
!   Which compression algorithm to use.  Needs building with zlib.
!
!   Values:
!     0 - no compression
!     1 - ZIP compression
!     2 - ZLIB compression [=ZIP plus meta-data and block-CRC's]
!   Default: 0
!   Applies: pgp_sym_encrypt, pgp_pub_encrypt
!
! compress-level::
!   How much to compress.  Bigger level compresses smaller but is slower.
!   0 disables compression.
!
!   Values: 0, 1-9
!   Default: 6
!   Applies: pgp_sym_encrypt, pgp_pub_encrypt
!
! convert-crlf::
!   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
!   behavior.
!
!   Values: 0, 1
!   Default: 0
!   Applies: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt
!
! disable-mdc::
!   Do not protect data with SHA-1.  Only good reason to use is 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.
!
!   Values: 0, 1
!   Default: 0
!   Applies: pgp_sym_encrypt, pgp_pub_encrypt
!
! enable-session-key::
!   Use separate session key.  Public-key encryption always uses separate
!   session key, this is for symmetric-key encryption, which by default
!   uses S2K directly.
!
!   Values: 0, 1
!   Default: 0
!   Applies: pgp_sym_encrypt
!
! s2k-mode::
!   Which S2K algorithm to use.
!
!   Values:
!     0 - Dangerous!  Without salt.
!     1 - With salt but with fixed iteration count.
!     3 - Variable iteration count.
!   Default: 3
!   Applies: pgp_sym_encrypt
!
! s2k-digest-algo::
!   Which digest algorithm to use in S2K calculation.
!
!   Values: md5, sha1
!   Default: sha1
!   Applies: pgp_sym_encrypt
!
! s2k-cipher-algo::
!   Which cipher to use for encrypting separate session key.
!
!   Values: bf, aes, aes128, aes192, aes256
!   Default: same as cipher-algo.
!   Applies: pgp_sym_encrypt
!
! unicode-mode::
!   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, only the data will be tagged as UTF-8.  Without this option
!   it will not be.
!
!   Values: 0, 1
!   Default: 0
!   Applies: pgp_sym_encrypt, pgp_pub_encrypt
!
!
! 5.9.  Generating keys with GnuPG
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!
! Generate a new key:
!
!     gpg --gen-key
!
! You need to pick "DSA and Elgamal" key type, others are sign-only.
!
! List keys:
!
!     gpg --list-secret-keys
!
! Export ascii-armored public key:
!
!     gpg -a --export KEYID > public.key
!
! Export ascii-armored secret key:
!
!     gpg -a --export-secret-keys KEYID > secret.key
!
! You need to use `dearmor()` on them before giving giving them to
! pgp_pub_* functions.  Or if you can handle binary data, you can drop
! "-a" from gpg.
!
!
! 5.10.  Limitations of PGP code
! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!
! - No support for signing.  That also means that it is not checked
!   whether the encryption subkey belongs to master key.
!
! - No support for RSA keys.  Only Elgamal encryption keys are supported
!
! - No support for several encryption subkeys.
!
!
! 6.  Raw encryption
! -------------------
!
! Those functions only run a cipher over data, they don't have any advanced
! features of PGP encryption.  In addition, they have some major problems:
!
! 1. They use user key directly as cipher key.
! 2. They don't provide any integrity checking, to see
!    if the encrypted data was modified.
! 3. They expect that users manage all encryption parameters
!    themselves, even IV.
! 4. They don't handle text.
!
! So, with the introduction of PGP encryption, usage of raw
! encryption functions is discouraged.
!
!
!     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
!
! Encrypt/decrypt data with cipher, padding data if needed.
!
! `type` parameter description in pseudo-noteup:
!
!     algo ['-' mode] ['/pad:' padding]
!
! Supported algorithms:
!
! * `bf`        - Blowfish
! * `aes`        - AES (Rijndael-128)
!
! Modes:
!
! * `cbc` - next block depends on previous. (default)
! * `ecb` - each block in encrypted separately.
!           (for testing only)
!
! Padding:
!
! * `pkcs` - data may be any length (default)
! * `none` - data must be multiple of cipher block size.
!
! 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.
!
! So, example:
!
!     encrypt(data, 'fooz', 'bf')
!
! is equal to
!
!     encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
!
!
! 7.  Credits
! ------------

  I have used code from following sources:

! `--------------------`-------------------------`----------------------
!   Algorithm            Author                    Source origin
! ----------------------------------------------------------------------
!   DES crypt()          David Burren and others   FreeBSD libcrypt
!   MD5 crypt()          Poul-Henning Kamp         FreeBSD libcrypt
!   Blowfish crypt()     Solar Designer            www.openwall.com
!   Blowfish cipher      Niels Provos              OpenBSD sys/crypto
!   Rijndael cipher      Brian Gladman             OpenBSD sys/crypto
!   MD5 and SHA1         WIDE Project              KAME kame/sys/crypto
!   SHA256/384/512       Aaron D. Gifford          OpenBSD sys/crypto
! ----------------------------------------------------------------------


! 8.  Legalese
! -------------

+ * I owe a beer to Poul-Henning.
  * This product includes software developed by Niels Provos.


+ 9.  References/Links
+ ---------------------
+
+ 9.1.  Useful reading
+ ~~~~~~~~~~~~~~~~~~~~~
+
+ http://www.openwall.com/crypt/[]::
+     Describes the crypt-blowfish algorithm.
+
+ http://www.stack.nl/~galactus/remailers/passphrase-faq.html[]::
+     How to choose good password.
+
+ http://world.std.com/~reinhold/diceware.html[]::
+     Interesting idea for picking passwords.
+
+ http://www.interhack.net/people/cmcurtin/snake-oil-faq.html[]::
+     Describes good and bad cryptography.
+
+
+ 9.2.  Technical references
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ http://www.ietf.org/rfc/rfc2440.txt[]::
+     OpenPGP message format
+
+ http://www.imc.org/draft-ietf-openpgp-rfc2440bis[]::
+     New version of RFC2440.
+
+ http://www.ietf.org/rfc/rfc1321.txt[]::
+     The MD5 Message-Digest Algorithm
+
+ http://www.ietf.org/rfc/rfc2104.txt[]::
+     HMAC: Keyed-Hashing for Message Authentication
+
+ http://www.usenix.org/events/usenix99/provos.html[]::
+     Comparison of crypt-des, crypt-md5 and bcrypt algorithms.
+
+ http://csrc.nist.gov/cryptval/des.htm[]::
+     Standards for DES, 3DES and AES.
+
+ http://en.wikipedia.org/wiki/Fortuna_(PRNG)[]::
+     Description of Fortuna CSPRNG.
+
+ http://jlcooke.ca/random/[]::
+     Jean-Luc Cooke Fortuna-based /dev/random driver for Linux.
+
+ http://www.cs.ut.ee/~helger/crypto/[]::
+     Collection of cryptology pointers.
+

--