I would like to do a interface change in pgcrypto. (Good

timing, I know :))  At the moment the digest() function returns
hexadecimal coded hash, but I want it to return pure binary.  I
have also included functions encode() and decode() which support
'base64' and 'hex' encodings, so if anyone needs digest() in hex
he can do encode(digest(...), 'hex').

Main reason for it is "to do one thing and do it well" :)

Another reason is if someone needs really lot of digesting, in
the end he wants to store the binary not the hexadecimal result.
It is really silly to convert it to hex then back to binary
again.  As I said if someone needs hex he can get it.

Well, and the real reason that I am doing encrypt()/decrypt()
functions and _they_ return binary.  For testing I like to see
it in hex occasionally, but it is really wrong to let them
return hex.  Only now it caught my eye that hex-coding in
digest() is wrong.  When doing digest() I thought about 'common
case' but hacking with psql is probably _not_ the common case :)

Marko Kreen

1 files changed, 11 insertions, 4 deletions

diff --git a/contrib/pgcrypto/README.pgcrypto b/contrib/pgcrypto/README.pgcrypto
index cfb05a7516..c449fdf4a9 100644
--- a/contrib/pgcrypto/README.pgcrypto
+++ b/contrib/pgcrypto/README.pgcrypto
@@ -1,14 +1,21 @@
 
 DESCRIPTION
 
-  Here is a implementation of crypto hashes for PostgreSQL.
-  It exports 2 functions to SQL level:
+  Here are various cryptographic and otherwise useful
+  functions for PostgreSQL.
+
+    encode(data, type)
+        encodes binary data into ASCII-only representation.
+	Types supported are 'hex' and 'base64'.
+
+    decode(data, type)
+    	decodes the data processed by encode()
 
     digest(data::text, hash_name::text)
-	which returns hexadecimal coded hash over data by
+	which returns cryptographic checksum over data by
 	specified algorithm. eg
 
-	> select digest('blah', 'sha1');
+	> select encode(digest('blah', 'sha1'), 'hex');
 	5bf1fd927dfb8679496a2e6cf00cbe50c1c87145
 
     digest_exists(hash_name::text)::bool