[Announce] pgcrypto 0.3 (long) - Mailing list pgsql-general

pgcrypto 0.3 / "why-dont-you-show-some-code" release

    http://www.l-t.ee/marko/pgsql/pgcrypto-0.3.tar.gz

This release is give people something to play with.
Parts of it need further thinking and lots of testing,
but I am tired of sitting on it.

Here follow parts from README to give an idea whats
going on.

------

SQL FUNCTIONS
=============

All arguments and return values are of type 'text' at the moment.
If any of arguments are NULL they return NULL.

Stable
------

   'Stable' means that the API should be final, functions do
   whatever they should do and they do not crash on me ;)

encode(data, type)
decode(data, type)

    Type is here 'hex' or 'base64'.  Self-explainatory.

digest(data, type)

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

digest_exists(type)

    Returns BOOL whether given hash exists.

[ Above functions are already in PostgreSQL 7.1 contrib tree ]

hmac(data, key, type)

    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)
    Returns BOOL.  It is separate function because all hashes
    cannot be used in HMAC.

crypt(password, salt)

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

gen_salt(type)

    Generates a new random salt for usage in crypt().  Type
    is 'des' (Old UNIX, not recommended) or 'md5' (md5-based
    crypt(), recommended).  Actually it supports also types
    'xdes' (Extended DES) and 'bf' (Blowfish) in case you use
    system crypt which supports them.

Unstable
--------

   Unstable means the binary format may change and/or pgcrypto may
   do different thing with different library.  This means if you
   encrypt something with them, then you may able to decrypt it
   only with same pgcrypto/library version you encrypted... if you
   are lucky :)  So be warned!!!

encrypt(data, key, type)
decrypt(data, key, type)
encrypt(data, key, iv, type)
decrypt(data, key, iv, type)

    Encrypt data with key using cipher 'type'.  E.g.

       encrypt(data, key, 'des')

    encrypts data with key "key" using DES in CBC
    mode.  Default IV (Initial Value) is zeroes if omitted.
    (Not all modes use IV, which will be ignored then in case
    it is provided).  Now something more interesting:

       encrypt(data, psw, 'bf-ecb/sha1')

    basically calculates SHA1 hash over data, appends it and
    encrypts the result with Blowfish in ECB mode.

    All of the above examples use generalized PCKS#5 padding,
    this simply means that user data need not be exactly
    multiple of block size, it is pgcrypto business feed the
    underlying ciphers correctly.  So the first example can be
    written as:

      encrypt(data, key, 'des-cbc/pad:pkcs')

    If you dont want pgcrypto to pad anything:

      encrypt(data, key, 'des/pad:none')

    HMAC can be used too:

      encrypt(data, key, 'bf/hmac-md5/pad:pkcs')

    In the future, pgcrypto will support key generators too.
    This way user can use human-memorizable key and keygen
    will generate real key (and IV too, if needed) from it,
    which look much more random.  [I guess:] this will add
    a little to the brute-force attack, but will harden
    significantly cryptoanalysis.  So good key must be
    choosed anyway...  So, one day something like this will
    be supported:

      encrypt(data, key, 'aes/sha1/keygen:s2k-simple')

    Decrypting similar, only in opposite direction.  If you
    have included a hash and it does not match, decrypt()
    will give error.

    [ TODO: more formal spec, limits ]

LIBRARIES
=========

* crypt()

    internal: 'des', 'md5'

    -lcrypt: ??? (whatever you have)

* other:

[ This only list of stuff libraries claim to support.  See in
  STATUS whether something works too.  OpenSSL/blowfish is the
  best choice at the moment.  Also SHA1/MD5 should work everywhere.

  As I am most interested in SHA1/MD5 and Blowfish (in the future
  Rijndael too)  they are the most (er, only) tested algorithms
  here.  On others there are no promises.  Both pgcrypto and
  library may mess something up. ]

internal (default):
    Hashes: MD5, SHA1
    Ciphers: none

OpenSSL (0.9.5a):
    Hashes:    MD5, SHA1, RIPEMD160, MD2
    Ciphers:    DES, DESX, DES3, RC5, RC4, RC2, IDEA,
        Blowfish, CAST5
    License:    BSD-like with strong advertisement
    Url:    http://www.openssl.org/
    Notes:    blowfish works.


mhash (0.8.9) + mcrypt (2.4.9):
    Hashes:    MD5, SHA1, CRC32, CRC32B, GOST, TIGER, RIPEMD160,
        HAVAL(256,224,192,160,128)
    Ciphers:    DES, DES3, CAST-128(CAST5), CAST-256, xTEA, 3-way,
            SKIPJACK, Blowfish, Twofish, LOKI97, RC2, RC4, RC6,
        Rijndael, MARS, PANAMA, WAKE, Serpent, IDEA, GOST,
        SAFER, SAFER+, Enigma
    License:    LGPL
    Url:    http://mcrypt.sourceforge.org/
    Url:    http://mhash.sourceforge.org/
    Notes:    Older MCRYPT does Blowfish wrong.  2.4.9
            does it correctly, but needs a patch (included).
        CVS has it fixed.

beecrypt 1.1.2:
    Hashes:    MD5, SHA1
    Ciphers:    Blowfish
    License:    LGPL
    Url:    http://beecrypt.virtualunlimited.com/
    Notes:    Does not support all Blowfish key sizes.

kerberos5 (heimdal 0.3c):
    Hashes: MD5, SHA1
    Ciphers: DES, DES3
    Notes:
    I dropped kerberos support, because it is
    quite hard to use it as general-purpose crypto library
    and it does not provide much either.

------

For todo/bugs/notes see distro.

Have fun!

--
marko