220 lines
5.5 KiB
Plaintext
220 lines
5.5 KiB
Plaintext
|
|
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() 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/
|
|
|
|
|
|
mhash (0.8.9) + mcrypt (2.4.16):
|
|
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-128/192/256, MARS, PANAMA, WAKE, Serpent, IDEA, GOST,
|
|
SAFER, SAFER+, Enigma
|
|
License: LGPL
|
|
Url: http://mcrypt.sourceforge.org/
|
|
Url: http://mhash.sourceforge.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.
|
|
|
|
|