From 06dc338ee9b971c23effe0b367596bf7687ff656 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Mon, 16 Oct 2000 03:25:17 +0000
Subject: [PATCH] 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
---
doc/src/sgml/client-auth.sgml | 16 +++++++++-
doc/src/sgml/installation.sgml | 20 +++++++++++-
doc/src/sgml/libpq.sgml | 32 ++++++++++++++++++-
doc/src/sgml/runtime.sgml | 58 +++++++++++++++++++++++++++++++++-
4 files changed, 122 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index b4895746bc5..78e6af41817 100644
--- 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.6 2000/09/06 19:54:45 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.7 2000/10/16 03:25:16 momjian Exp $ -->
<chapter id="client-authentication">
<title>Client Authentication</title>
@@ -80,6 +80,20 @@ hostssl <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><literal>hostssl</literal></term>
<listitem>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 1cf60bf127b..44ab809973b 100644
--- 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.23 2000/10/08 21:13:27 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.24 2000/10/16 03:25:16 momjian Exp $ -->
<chapter id="installation">
<title><![%flattext-install-include[<productname>PostgreSQL</> ]]>Installation Instructions</title>
@@ -665,6 +665,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 d8d8b3ca929..380fb6bdf44 100644
--- 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.42 2000/10/03 19:16:16 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.43 2000/10/16 03:25:16 momjian Exp $
-->
<chapter id="libpq-chapter">
@@ -188,6 +188,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
@@ -663,6 +674,25 @@ SSL *PQgetssl(const PGconn *conn);
automatically include <filename>ssl.h</filename> from OpenSSL.
</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 7b1fbd68a33..735e8ac8ef5 100644
--- 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.27 2000/10/08 09:25:35 ishii Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.28 2000/10/16 03:25:17 momjian Exp $
-->
<Chapter Id="runtime">
@@ -1695,6 +1695,62 @@ openssl x509 -inform PEM -outform PEM -in newreq.pem -out newkey_no_passphrase.p
</para>
</sect1>
+ <sect1 id="ssl">
+ <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 id="ssh">
<title>Secure TCP/IP Connections with SSH tunnels</title>
--
GitLab