SSL improvements:

	o read global SSL configuration file
	o add GUC "ssl_ciphers" to control allowed ciphers
	o add libpq environment variable PGSSLKEY to control SSL hardware keys

Victor B. Wagner

3 files changed, 77 insertions, 7 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index e5c73b4e361..aa5c15f1a01 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.110 2007/02/08 15:46:03 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.111 2007/02/16 02:59:40 momjian Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -569,6 +569,20 @@ SET ENABLE_SEQSCAN TO OFF;
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-ssl-ciphers" xreflabel="ssl-ciphers">
+      <term><varname>ssl_ciphers> (<type>string</type>)</term>
+      <indexterm>
+       <primary><varname>ssl_ciphers</> configuration parameter</primary>
+      </indexterm>
+      <listitem>
+       <para>
+        Specifies a list of <acronym>SSL</> ciphers which can be used to
+        establish secure connections. See the <application>openssl</>
+        manual page for a list of supported ciphers.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-password-encryption" xreflabel="password_encryption">
       <term><varname>password_encryption</varname> (<type>boolean</type>)</term>
       <indexterm>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 4c017334e1d..dd8ab08fe2b 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.228 2007/02/06 03:03:11 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.229 2007/02/16 02:59:40 momjian Exp $ -->
 
  <chapter id="libpq">
   <title><application>libpq</application> - C Library</title>
@@ -4175,6 +4175,18 @@ setting, and is only available if
 <listitem>
 <para>
 <indexterm>
+<primary><envar>PGSSLKEY</envar></primary>
+</indexterm>
+<envar>PGSSLKEY</envar>
+specifies the hardware token which stores the secret key for the client
+certificate, instead of a file. The value of this variable should consist
+of a colon-separated engine name (engines are <productname>OpenSSL</>
+loadable modules) and an engine-specific key identifier.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm>
  <primary><envar>PGKRBSRVNAME</envar></primary>
 </indexterm>
 <envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use when
@@ -4438,20 +4450,45 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?uniqueMember?one?(cn=mydatabase)
    for increased security. See <xref linkend="ssl-tcp"> for details
    about the server-side <acronym>SSL</> functionality.
   </para>
-
+  <para>
+  <application>libpq</application> reads the system-wide
+  <productname>OpenSSL</productname> configuration file. By default, this
+  file is named <filename>openssl.cnf</filename> and is located in the
+  directory reported by <application>openssl</>:
+  <programlisting>
+  openssl version -d
+  </programlisting>
+  The default can be overriden by setting environment variable
+  <envar>OPENSSL_CONF</envar> to the name of the desired configuration
+  file.
+  </para>
   <para>
    If the server demands a client certificate, 
    <application>libpq</application>
    will send the certificate stored in file
    <filename>~/.postgresql/postgresql.crt</> within the user's home directory.
    A matching private key file <filename>~/.postgresql/postgresql.key</>
-   must also be present, and must not be world-readable.
+   must also be present, and must not be world-readable, unless the secret
+   key is stored in a hardware token, as specified by
+   <envar>PGSSLKEY</envar>.
    (On Microsoft Windows these files are named
    <filename>%APPDATA%\postgresql\postgresql.crt</filename> and
    <filename>%APPDATA%\postgresql\postgresql.key</filename>.)
   </para>
 
   <para>
+   If the environment variable <envar>PGSSLKEY</envar> is set, its value
+   should consist of a colon-separated engine name and key identifier. In
+   this case, <application>libpq</application> will load the specified
+   engine, i.e. the <productname>OpenSSL</> module which supports special
+   hardware and reference the key with the specified identifier.
+   Identifiers are engine-specific. Typically, cryptography hardware tokens
+   do not reveal secret keys to the application. Instead, applications
+   delegate all cryptography operations which require the secret key to
+   the hardware token.
+  </para>	
+	
+  <para>
    If the file <filename>~/.postgresql/root.crt</> is present in the user's
    home directory,
    <application>libpq</application> will use the certificate list stored
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 4baec332766..7bed97a86f3 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.376 2007/02/01 00:28:18 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.377 2007/02/16 02:59:40 momjian Exp $ -->
 
 <chapter Id="runtime">
  <title>Operating System Environment</title>
@@ -1516,6 +1516,25 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
   </para>
 
   <para>
+   <productname>OpenSSL</productname> supports a wide range of ciphers
+   and authentication algorithms, whose strength varies significantly.
+   You can restrict the list of ciphers which can be used to connect to
+   your server using the <xref linkend="guc-ssl-ciphers"> parameter.
+  </para>
+
+  <para>
+   <productname>PostgreSQL</productname> reads a system-wide
+   <productname>OpenSSL</productname> configuration file. By default this
+   file is named <filename>openssl.cnf</filename> and is located in the
+   directory reported by <application>openssl</>:
+   <programlisting>
+   openssl version -d
+   </programlisting>
+   This default can be overriden by setting environment variable
+   <envar>OPENSSL_CONF</envar> to the name of desired configuration file.
+  </para>
+
+  <para>
    For details on how to create your server private key and certificate,
    refer to the <productname>OpenSSL</> documentation. A
    self-signed certificate can be used for testing, but a
@@ -1528,8 +1547,8 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
 <programlisting>
 openssl req -new -text -out server.req
 </programlisting>
-   Fill out the information that <command>openssl</> asks for. Make sure
-   that you enter the local host name as <quote>Common Name</>; the challenge
+   Fill out the information that <application>openssl</> asks for. Make sure
+   you enter the local host name as <quote>Common Name</>; the challenge
    password can be left blank. The program will generate a key that is
    passphrase protected; it will not accept a passphrase that is less
    than four characters long. To remove the passphrase (as you must if