Here is a patch against the same cvs tree as the SSL patch (Aug 20).

I hope I didn't mess the SGML up too bad, but somebody should definitly
look that over. I tried to steal as much as I could from around :-)

This patch updates:
* Installation instructions (paragraph on how to compile with openssl)
* Documentation of pg_hba.conf (added "hostssl" record docs)
* Libpq documentation (added connection option, documentation of
  PQgetssl() function)
* Add section on SSL to "Server Runtime Environment"

If you beleive any particular area needs more attention, please let me know.

//Magnus

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 31d910b302ac08677b5a0b1429c99ea8f08303c1..6cf5aef377d23679178c3734005cf2c26e6f66c4 100644 (file)
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.4 2000/08/25 10:00:29 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.5 2000/08/29 04:15:43 momjian Exp $ -->
 
 <chapter id="client-authentication">
  <title>Client Authentication</title>
@@ -53,6 +53,7 @@
    <synopsis>
 local <replaceable>database</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
 host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
+hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
     </synopsis>
    The meaning of the fields is as follows:
 
@@ -79,6 +80,20 @@ host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <
      </listitem>
     </varlistentry>
 
+    <varlistentry>
+     <term><literal>hostssl</literal></term>
+     <listitem>
+      <para>
+       This record pertains to connection attemps with SSL over
+       TCP/IP. Note that SSL connections are completely disabled
+       unless the server is started with the <option>-i</option>,
+       and also require ordinary TCP/IP connections to be enabled.
+       SSL connections also require SSL support to be enabled in
+       the backend at compile time.
+      </para>
+     </listitem>
+    </varlistentry>
+
     <varlistentry>
      <term><replaceable>database</replaceable></term>
      <listitem>

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 62ac008083a7a0e56db4329ead42fb21f340313c..261c283ac4d15141be0d37c178608ff1b9a7d125 100644 (file)
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.14 2000/08/25 10:00:29 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.15 2000/08/29 04:15:43 momjian Exp $ -->
 
 <chapter id="installation">
  <title><![%flattext-install-include[<productname>PostgreSQL</> ]]>Installation Instructions</title>
@@ -577,6 +577,24 @@ su - postgres
        </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term>--with-openssl=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         Build with support for SSL (encrypted) connections. 
+         This requires the OpenSSL library to be installed.
+         The <replaceable>DIRECTORY</> argument specifies the
+         root directory of the OpenSSL installation.
+        </para>
+
+        <para>
+         <filename>configure</> will check for the required header
+         files and libraries to make sure that your OpenSSL
+         installation is sufficient before proceeding.
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
        <term>--enable-syslog</term>
        <listitem>

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index c14f9ee260d939979fd10829c1ab42e9dfaef0ee..648406e546250774b556177efa90d568c82cd013 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.38 2000/05/02 20:01:52 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.39 2000/08/29 04:15:43 momjian Exp $
 -->
 
  <chapter id="libpq-chapter">
@@ -177,6 +177,17 @@ PGconn *PQconnectdb(const char *conninfo)
      </para>
      </listitem>
     </varlistentry>
+
+    <varlistentry>
+     <term><literal>requiressl</literal></term>
+     <listitem>
+     <para>
+      Set to '1' to require SSL connection to the backend. Libpq
+      will then refuse to connect if the server does not support
+      SSL. Set to '0' (default) to negotiate with server.
+     </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
 
    If  any  parameter is unspecified, then the corresponding
@@ -633,6 +644,25 @@ int PQbackendPID(const PGconn *conn);
        server host, not the local host!
       </para>
      </listitem>
+
+     <listitem>
+      <para>
+       <function>PQgetssl</function>
+       Returns the SSL structure used in the connection, or NULL
+       if SSL is not in use. 
+       <synopsis>
+SSL *PQgetssl(const PGconn *conn);
+       </synopsis>
+       This structure can be used to verify encryption levels, check
+       server certificate and more. Refer to the OpenSSL documentation
+       for information about this structure.
+      </para>
+      <para>
+       You must define <literal>USE_SSL</literal> in order to get the
+       prototype for this function. Doing this will also 
+       automatically include <filename>ssl.h</filename> from OpenSSL.
+      </para>
+     </listitem>
     </itemizedlist>
    </para>
   </sect1>

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 0142b6b64520abbfa96ebae87c5046111ef52b7c..69e40f6f58c90581a5d80423243c11e2b911cf51 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.21 2000/08/28 11:57:40 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.22 2000/08/29 04:15:43 momjian Exp $
 -->
 
 <Chapter Id="runtime">
@@ -1726,6 +1726,62 @@ perl: warning: Falling back to the standard locale ("C").
   </para>
  </sect1>
 
+ <sect1>
+  <title>Secure TCP/IP Connection with SSL</title>
+
+  <para>
+   PostgreSQL has native support for connections over SSL to encrypt
+   client/server communications for increased security. This requires
+   <productname>OpenSSL</productname> to be installed on both client
+   and server systems and support enabled at compile-time using
+   the configure script.
+  </para>
+
+  <para>
+   With SSL support compiled in, the Postgres backend can be 
+   started with argument -l to enable SSL connections. 
+   When starting in SSL mode, the postmaster will look for the 
+   files <filename>server.key</filename> and
+   <filename>server.cert</filename> in the <envar>PGDATA</envar>
+   directory. These files should contain the server private key and
+   certificate respectively. If the private key is protected with a 
+   passphrase, the postmaster will prompt for the passphrase and not 
+   start until it has been provided.
+  </para>
+
+  <para>
+   The postmaster will listen for both standard and SSL connections
+   on the same TCP/IP port, and will negotiate with any connecting
+   client wether to use SSL or not. Use the <filename>pg_hba.conf</filename>
+   file to optionally require SSL in order to accept a connection.
+  </para>
+
+  <para>
+   For details on how to create your server private key and certificate,
+   refer to the OpenSSL documentation. A simple self-signed certificate
+   can be used to get started testing, but a certificate signed by a CA
+   (either one of the global CAs or a local one) should be used in 
+   production so the client can verify the servers identity. To create
+   a quick self-signed certificate, use the <filename>CA.pl</filename>
+   script included in OpenSSL:
+<programlisting>
+   CA.pl -newcert
+</programlisting>
+   Fill out the information the script asks for. Make sure to enter
+   the local hostname as Common Name. The script will generate a key
+   which is passphrase protected. To remove the passphrase (required
+   if you want automatic startup of the postmaster), run the command
+<programlisting>
+   openssl x509 -inform PEM -outform PEM -in newreq.pem -out newkey_no_passphrase.pem
+</programlisting>
+   Enter the old passphrase to unlock the existing key. Copy the file
+   <filename>newreq.pem</filename> to <filename>PGDATA/server.cert</filename>
+   and <filename>newkey_no_passphrase.pem</filename> to 
+   <filename>PGDATA/server.key</filename>. Remove the PRIVATE KEY part
+   from the <filename>server.cert</filename> using any text editor.
+  </para>
+ </sect1>
+
  <sect1>
   <title>Secure TCP/IP Connection with SSH</title>