sslinfo contrib module - information about current SSL certificate

Author: Victor Wagner <vitus@cryptocom.ru>

Author: petere

contrib/Makefile

@@ -1,4 +1,4 @@
-# $PostgreSQL: pgsql/contrib/Makefile,v 1.66 2006/05/30 13:25:57 momjian Exp $
+# $PostgreSQL: pgsql/contrib/Makefile,v 1.67 2006/09/04 15:07:46 petere Exp $
 
 subdir = contrib
 top_builddir = ..
@@ -36,6 +36,10 @@ WANTED_DIRS = \
 		userlock	\
 		vacuumlo
 
+ifeq ($(with_openssl),yes)
+WANTED_DIRS += sslinfo
+endif
+
 # Missing:
 #		adddepend	\ (does not have a makefile)
 #		mSQL-interface	\ (requires msql installed)

contrib/sslinfo/Makefile

@@ -0,0 +1,9 @@
+subdir = contrib/sslinfo
+top_builddir = ../..
+include $(top_builddir)/src/Makefile.global
+
+MODULES = sslinfo
+DATA_built = sslinfo.sql
+DOC = README.pgsslinfo
+
+include ../contrib-global.mk	

contrib/sslinfo/README.sslinfo

@@ -0,0 +1,121 @@
+sslinfo - information about current SSL certificate for PostgreSQL
+==================================================================
+Copyright (c) 2006 Cryptocom LTD
+Author: Victor Wagner <vitus@cryptocom.ru>
+E-Mail of Cryptocom OpenSSL development group: <openssl@cryptocom.ru>
+
+
+1. Notes
+--------
+This extension won't build unless your PostgreSQL server is configured
+with --with-openssl.  Information provided with these functions would
+be completely useless if you don't use SSL to connect to database.
+
+
+2. Functions Description
+------------------------
+
+2.1. ssl_is_used()
+~~~~~~~~~~~~~~~~~~
+
+	ssl_is_used() RETURNS boolean;
+
+Returns TRUE, if current connection to server uses SSL and FALSE
+otherwise.
+
+2.2. ssl_client_cert_present()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+	ssl_client_cert_present() RETURNS boolean
+
+Returns TRUE if current client have presented valid SSL client
+certificate to the server and FALSE otherwise (e.g., no SSL,
+certificate hadn't be requested by server).
+
+2.3. ssl_client_serial() 
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+	ssl_client_serial() RETURNS numeric
+
+Returns serial number of current client certificate.  The combination
+of certificate serial number and certificate issuer is guaranteed to
+uniquely identify certificate (but not its owner -- the owner ought to
+regularily change his keys, and get new certificates from the issuer).
+
+So, if you run you own CA and allow only certificates from this CA to
+be accepted by server, the serial number is the most reliable (albeit
+not very mnemonic) means to indentify user.
+
+2.4. ssl_client_dn()
+~~~~~~~~~~~~~~~~~~~~
+	
+	ssl_client_dn() RETURNS text
+
+Returns the full subject of current client certificate, converting
+character data into the current database encoding.  It is assumed that
+if you use non-Latin characters in the certificate names, your
+database is able to represent these characters, too.  If your database
+uses the SQL_ASCII encoding, non-Latin characters in the name will be
+represented as UTF-8 sequences.
+
+The result looks like '/CN=Somebody /C=Some country/O=Some organization'.
+
+2.5. ssl_issuer_dn()
+~~~~~~~~~~~~~~~~~~~~
+
+Returns the full issuer name of the client certificate, converting
+character data into current database encoding.
+
+The combination of the return value of this function with the
+certificate serial number uniquely identifies the certificate.
+
+The result of this function is really useful only if you have more
+than one trusted CA certificate in your server's root.crt file, or if
+this CA has issued some intermediate certificate authority
+certificates.
+
+2.6. ssl_client_dn_field()
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+	ssl_client_dn_field(fieldName text) RETURNS text
+
+This function returns the value of the specified field in the
+certificate subject.  Field names are string constants that are
+converted into ASN1 object identificators using the OpenSSL object
+database.  The following values are acceptable:
+
+	commonName (alias CN)
+	surname (alias SN)
+	name
+	givenName (alias GN)
+	countryName (alias C) 
+	localityName (alias L)
+	stateOrProvinceName (alias ST)
+	organizationName (alias O)
+	organizationUnitName (alias OU)
+	title
+	description
+	initials
+	postalCode
+	streetAddress
+	generationQualifier
+	description
+	dnQualifier
+	x500UniqueIdentifier
+	pseudonim
+	role
+	emailAddress
+	
+All of these fields are optional, except commonName.  It depends
+entirely on your CA policy which of them would be included and which
+wouldn't.  The meaning of these fields, howeer, is strictly defined by
+the X.500 and X.509 standards, so you cannot just assign arbitrary
+meaning to them.
+
+2.7 ssl_issuer_field()
+~~~~~~~~~~~~~~~~~~~
+
+	ssl_issuer_field(fieldName text) RETURNS text;
+
+Does same as ssl_client_dn_field, but for the certificate issuer
+rather than the certificate subject.