<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.5 2000/08/29 04:15:43 momjian Exp $ -->

hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]

<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>

<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.15 2000/08/29 04:15:43 momjian Exp $ -->

<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>

$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.39 2000/08/29 04:15:43 momjian Exp $

<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>

<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>

$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.22 2000/08/29 04:15:43 momjian Exp $

<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>