postgresql/contrib/pgcrypto
Bruce Momjian ee85595d46 > Please find enclose a submission to fix these problems.
>
> The patch adds missing the "libpgport.a" file to the installation under
> "install-all-headers". It is needed by some contribs. I install the
> library in "pkglibdir", but I was wondering whether it should be "libdir"?
> I was wondering also whether it would make sense to have a "libpgport.so"?
>
> It fixes various macros which are used by contrib makefiles, especially
> libpq_*dir and LDFLAGS when used under PGXS. It seems to me that they are
> needed to
>
> It adds the ability to test and use PGXS with contribs, with "make
> USE_PGXS=1". Without the macro, this is exactly as before, there should be
> no difference, esp. wrt the vpath feature that seemed broken by previous
> submission. So it should not harm anybody, and it is useful at least to me.
>
> It fixes some inconsistencies in various contrib makefiles
> (useless override, ":=" instead of "=").

Fabien COELHO
2004-08-20 20:13:10 +00:00
..
expected SET autocommit no longer needed in /contrib because pg_regress.sh does 2002-10-21 01:42:14 +00:00
sql SET autocommit no longer needed in /contrib because pg_regress.sh does 2002-10-21 01:42:14 +00:00
API * regression tests 2001-09-30 22:18:29 +00:00
blf.c Remove gratuitous redefinition of inline, which should already have been 2002-01-29 15:40:45 +00:00
blf.h New pgindent run with fixes suggested by Tom. Patch manually reviewed, 2001-11-05 17:46:40 +00:00
crypt-blowfish.c * When postgres.h does not define BYTE_ENDIAN pgcrypto 2001-11-29 19:40:37 +00:00
crypt-des.c Fix various recent build and regression-test problems in contrib/. 2003-05-14 03:27:22 +00:00
crypt-gensalt.c * When postgres.h does not define BYTE_ENDIAN pgcrypto 2001-11-29 19:40:37 +00:00
crypt-md5.c make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00
internal.c Solve the 'Turkish problem' with undesirable locale behavior for case 2004-05-07 00:24:59 +00:00
Makefile > Please find enclose a submission to fix these problems. 2004-08-20 20:13:10 +00:00
md5.c Solve the 'Turkish problem' with undesirable locale behavior for case 2004-05-07 00:24:59 +00:00
md5.h make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00
mhash.c Solve the 'Turkish problem' with undesirable locale behavior for case 2004-05-07 00:24:59 +00:00
misc.c pgindent run on all C files. Java run to follow. initdb/regression 2001-10-25 05:50:21 +00:00
openssl.c make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00
pgcrypto.c Solve the 'Turkish problem' with undesirable locale behavior for case 2004-05-07 00:24:59 +00:00
pgcrypto.h make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00
pgcrypto.sql.in Backend support for autocommit removed, per recent discussions. The 2003-05-14 03:26:03 +00:00
px-crypt.c Solve the 'Turkish problem' with undesirable locale behavior for case 2004-05-07 00:24:59 +00:00
px-crypt.h make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00
px-hmac.c make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00
px.c Solve the 'Turkish problem' with undesirable locale behavior for case 2004-05-07 00:24:59 +00:00
px.h make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00
random.c make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00
README.pgcrypto * regression tests 2001-09-30 22:18:29 +00:00
rijndael.c Fix unsafe macro definitions (which were producing incorrect code, 2002-09-05 21:08:26 +00:00
rijndael.h pgcrypto uses non-standard type uint, which causes compile 2001-11-20 15:50:53 +00:00
rijndael.tbl Add missing pgcrypto file. 2001-08-21 01:32:01 +00:00
sha1.c Solve the 'Turkish problem' with undesirable locale behavior for case 2004-05-07 00:24:59 +00:00
sha1.h make sure the $Id tags are converted to $PostgreSQL as well ... 2003-11-29 22:41:33 +00:00

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.