Skip to content

Commit 06dc338

Browse files
bmomjianbmomjian
committed
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
1 parent 68b5996 commit 06dc338

File tree

4 files changed

+122
-4
lines changed

4 files changed

+122
-4
lines changed

‎doc/src/sgml/client-auth.sgml

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.6 2000/09/06 19:54:45 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.7 2000/10/16 03:25:16 momjian Exp $ -->
22

33
<chapter id="client-authentication">
44
<title>Client Authentication</title>
@@ -80,6 +80,20 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
8080
</listitem>
8181
</varlistentry>
8282

83+
<varlistentry>
84+
<term><literal>hostssl</literal></term>
85+
<listitem>
86+
<para>
87+
This record pertains to connection attemps with SSL over
88+
TCP/IP. Note that SSL connections are completely disabled
89+
unless the server is started with the <option>-i</option>,
90+
and also require ordinary TCP/IP connections to be enabled.
91+
SSL connections also require SSL support to be enabled in
92+
the backend at compile time.
93+
</para>
94+
</listitem>
95+
</varlistentry>
96+
8397
<varlistentry>
8498
<term><literal>hostssl</literal></term>
8599
<listitem>

‎doc/src/sgml/installation.sgml

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.23 2000/10/08 21:13:27 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.24 2000/10/16 03:25:16 momjian Exp $ -->
22

33
<chapter id="installation">
44
<title><![%flattext-install-include[<productname>PostgreSQL</> ]]>Installation Instructions</title>
@@ -665,6 +665,24 @@ su - postgres
665665
</listitem>
666666
</varlistentry>
667667

668+
<varlistentry>
669+
<term>--with-openssl=<replaceable>DIRECTORY</></term>
670+
<listitem>
671+
<para>
672+
Build with support for SSL (encrypted) connections.
673+
This requires the OpenSSL library to be installed.
674+
The <replaceable>DIRECTORY</> argument specifies the
675+
root directory of the OpenSSL installation.
676+
</para>
677+
678+
<para>
679+
<filename>configure</> will check for the required header
680+
files and libraries to make sure that your OpenSSL
681+
installation is sufficient before proceeding.
682+
</para>
683+
</listitem>
684+
</varlistentry>
685+
668686
<varlistentry>
669687
<term>--enable-syslog</term>
670688
<listitem>

‎doc/src/sgml/libpq.sgml

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.42 2000/10/03 19:16:16 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.43 2000/10/16 03:25:16 momjian Exp $
33
-->
44

55
<chapter id="libpq-chapter">
@@ -188,6 +188,17 @@ PGconn *PQconnectdb(const char *conninfo)
188188
</para>
189189
</listitem>
190190
</varlistentry>
191+
192+
<varlistentry>
193+
<term><literal>requiressl</literal></term>
194+
<listitem>
195+
<para>
196+
Set to '1' to require SSL connection to the backend. Libpq
197+
will then refuse to connect if the server does not support
198+
SSL. Set to '0' (default) to negotiate with server.
199+
</para>
200+
</listitem>
201+
</varlistentry>
191202
</variablelist>
192203

193204
If any parameter is unspecified, then the corresponding
@@ -663,6 +674,25 @@ SSL *PQgetssl(const PGconn *conn);
663674
automatically include <filename>ssl.h</filename> from OpenSSL.
664675
</para>
665676
</listitem>
677+
678+
<listitem>
679+
<para>
680+
<function>PQgetssl</function>
681+
Returns the SSL structure used in the connection, or NULL
682+
if SSL is not in use.
683+
<synopsis>
684+
SSL *PQgetssl(const PGconn *conn);
685+
</synopsis>
686+
This structure can be used to verify encryption levels, check
687+
server certificate and more. Refer to the OpenSSL documentation
688+
for information about this structure.
689+
</para>
690+
<para>
691+
You must define <literal>USE_SSL</literal> in order to get the
692+
prototype for this function. Doing this will also
693+
automatically include <filename>ssl.h</filename> from OpenSSL.
694+
</para>
695+
</listitem>
666696
</itemizedlist>
667697
</para>
668698
</sect1>

‎doc/src/sgml/runtime.sgml

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.27 2000/10/08 09:25:35 ishii Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.28 2000/10/16 03:25:17 momjian Exp $
33
-->
44

55
<Chapter Id="runtime">
@@ -1695,6 +1695,62 @@ openssl x509 -inform PEM -outform PEM -in newreq.pem -out newkey_no_passphrase.p
16951695
</para>
16961696
</sect1>
16971697

1698+
<sect1 id="ssl">
1699+
<title>Secure TCP/IP Connection with SSL</title>
1700+
1701+
<para>
1702+
PostgreSQL has native support for connections over SSL to encrypt
1703+
client/server communications for increased security. This requires
1704+
<productname>OpenSSL</productname> to be installed on both client
1705+
and server systems and support enabled at compile-time using
1706+
the configure script.
1707+
</para>
1708+
1709+
<para>
1710+
With SSL support compiled in, the Postgres backend can be
1711+
started with argument -l to enable SSL connections.
1712+
When starting in SSL mode, the postmaster will look for the
1713+
files <filename>server.key</filename> and
1714+
<filename>server.cert</filename> in the <envar>PGDATA</envar>
1715+
directory. These files should contain the server private key and
1716+
certificate respectively. If the private key is protected with a
1717+
passphrase, the postmaster will prompt for the passphrase and not
1718+
start until it has been provided.
1719+
</para>
1720+
1721+
<para>
1722+
The postmaster will listen for both standard and SSL connections
1723+
on the same TCP/IP port, and will negotiate with any connecting
1724+
client wether to use SSL or not. Use the <filename>pg_hba.conf</filename>
1725+
file to optionally require SSL in order to accept a connection.
1726+
</para>
1727+
1728+
<para>
1729+
For details on how to create your server private key and certificate,
1730+
refer to the OpenSSL documentation. A simple self-signed certificate
1731+
can be used to get started testing, but a certificate signed by a CA
1732+
(either one of the global CAs or a local one) should be used in
1733+
production so the client can verify the servers identity. To create
1734+
a quick self-signed certificate, use the <filename>CA.pl</filename>
1735+
script included in OpenSSL:
1736+
<programlisting>
1737+
CA.pl -newcert
1738+
</programlisting>
1739+
Fill out the information the script asks for. Make sure to enter
1740+
the local hostname as Common Name. The script will generate a key
1741+
which is passphrase protected. To remove the passphrase (required
1742+
if you want automatic startup of the postmaster), run the command
1743+
<programlisting>
1744+
openssl x509 -inform PEM -outform PEM -in newreq.pem -out newkey_no_passphrase.pem
1745+
</programlisting>
1746+
Enter the old passphrase to unlock the existing key. Copy the file
1747+
<filename>newreq.pem</filename> to <filename>PGDATA/server.cert</filename>
1748+
and <filename>newkey_no_passphrase.pem</filename> to
1749+
<filename>PGDATA/server.key</filename>. Remove the PRIVATE KEY part
1750+
from the <filename>server.cert</filename> using any text editor.
1751+
</para>
1752+
</sect1>
1753+
16981754
<sect1 id="ssh">
16991755
<title>Secure TCP/IP Connections with SSH tunnels</title>
17001756

0 commit comments

Comments
 (0)