README.pgcrypto 5.1 KB
Newer Older
1

Bruce Momjian's avatar
Bruce Momjian committed
2 3 4
pgcrypto 0.4 - cryptographic functions for PostgreSQL.
======================================================
by Marko Kreen <marko@l-t.ee>
5

6

Bruce Momjian's avatar
Bruce Momjian committed
7 8
INSTALLATION
============
9

Bruce Momjian's avatar
Bruce Momjian committed
10
Edit makefile, if you want to use any external library.
11

12 13 14 15 16 17
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.
18 19 20

After editing Makefile:

Bruce Momjian's avatar
Bruce Momjian committed
21 22
make
make install
23

Bruce Momjian's avatar
Bruce Momjian committed
24 25 26 27 28
To run regression tests, install both PostgreSQL and pgcrypto
and then run

make installcheck

Bruce Momjian's avatar
Bruce Momjian committed
29 30
SQL FUNCTIONS
=============
31

Bruce Momjian's avatar
Bruce Momjian committed
32
	If any of arguments are NULL they return NULL.
33

Bruce Momjian's avatar
Bruce Momjian committed
34
digest(data::bytea, type::text)::bytea
35

Bruce Momjian's avatar
Bruce Momjian committed
36 37
	Type is here the algorithm to use. E.g. 'md5', 'sha1', ...
	Returns binary hash.
38

Bruce Momjian's avatar
Bruce Momjian committed
39
digest_exists(type::text)::bool
40

Bruce Momjian's avatar
Bruce Momjian committed
41
	Returns BOOL whether given hash exists.
42

Bruce Momjian's avatar
Bruce Momjian committed
43
hmac(data::bytea, key::bytea, type::text)::bytea
44

Bruce Momjian's avatar
Bruce Momjian committed
45 46 47 48 49 50 51
	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. ]
52

Bruce Momjian's avatar
Bruce Momjian committed
53 54 55
hmac_exists(type::text)::bool
	Returns BOOL.  It is separate function because all hashes
	cannot be used in HMAC.
56

Bruce Momjian's avatar
Bruce Momjian committed
57
crypt(password::text, salt::text)::text
58

Bruce Momjian's avatar
Bruce Momjian committed
59 60 61
	Calculates UN*X crypt(3) style hash.  Useful for storing
	passwords.  For generating salt you should use the
	gen_salt() function.  Usage:
62

Bruce Momjian's avatar
Bruce Momjian committed
63 64 65 66 67
	New password:
	
	  UPDATE .. SET pswhash = crypt(new_psw, gen_salt('md5'));
	
	Authentication:
68

Bruce Momjian's avatar
Bruce Momjian committed
69 70 71 72 73
	  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...
74

Bruce Momjian's avatar
Bruce Momjian committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
	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.

90 91 92
gen_salt(type::text, rounds::int4)::text

	same as above, but lets user specify iteration count
Neil Conway's avatar
Neil Conway committed
93
	for algorithm.  Number is algorithm specific:
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110

	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.

Bruce Momjian's avatar
Bruce Momjian committed
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
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
==========

Neil Conway's avatar
Neil Conway committed
152
The standard functionality at the moment consists of
Bruce Momjian's avatar
Bruce Momjian committed
153 154 155 156 157

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

Neil Conway's avatar
Neil Conway committed
158
TODO: write standard names for optional ciphers too.
Bruce Momjian's avatar
Bruce Momjian committed
159 160 161 162 163 164 165 166 167 168 169 170

LIBRARIES
=========

* crypt()

    internal: des, xdes, md5, bf

    -lcrypt: ??? (whatever you have)

* other:

Neil Conway's avatar
Neil Conway committed
171 172
[ This only lists stuff that the libraries claim to support.  So
  pgcrypto may work with all of them.  But ATM tested are only the
Bruce Momjian's avatar
Bruce Momjian committed
173 174 175 176 177 178 179 180
  standard ciphers.  On others pgcrypto and library may mess something
  up. You have been warned.  ]

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


Neil Conway's avatar
Neil Conway committed
181
OpenSSL (0.9.7):
Bruce Momjian's avatar
Bruce Momjian committed
182
    Hashes:	MD5, SHA1, RIPEMD160, MD2   
Neil Conway's avatar
Neil Conway committed
183
    Ciphers:	Blowfish, AES, CAST5, DES, 3DES
Bruce Momjian's avatar
Bruce Momjian committed
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
    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.
206

207