pgcrypto 0.4 - cryptographic functions for PostgreSQL. ====================================================== by Marko Kreen 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() function. So if you plan using it, you should definitely change that by editing Makefile. You should be using 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 algotithm 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. 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 consist of Hashes: md5, sha1 Ciphers: bf, aes Modes: cbc, ecb TODO: write stardard names for optional ciphers too. LIBRARIES ========= * crypt() internal: des, xdes, md5, bf -lcrypt: ??? (whatever you have) * other: [ This only list of stuff libraries claim to support. So pgcrypto may work with all of them. But ATM tested aree 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.6): 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/ 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.