Skip to content

Commit c51041f

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 46426b6 commit c51041f

File tree

4 files changed

+123
-4
lines changed

4 files changed

+123
-4
lines changed

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

Lines changed: 16 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.4 2000/08/25 10:00:29 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.5 2000/08/29 04:15:43 momjian Exp $ -->
22

33
<chapter id="client-authentication">
44
<title>Client Authentication</title>
@@ -53,6 +53,7 @@
5353
<synopsis>
5454
local <replaceable>database</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
5555
host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
56+
hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
5657
</synopsis>
5758
The meaning of the fields is as follows:
5859

@@ -79,6 +80,20 @@ host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <
7980
</listitem>
8081
</varlistentry>
8182

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+
8297
<varlistentry>
8398
<term><replaceable>database</replaceable></term>
8499
<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.14 2000/08/25 10:00:29 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.15 2000/08/29 04:15:43 momjian Exp $ -->
22

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

580+
<varlistentry>
581+
<term>--with-openssl=<replaceable>DIRECTORY</></term>
582+
<listitem>
583+
<para>
584+
Build with support for SSL (encrypted) connections.
585+
This requires the OpenSSL library to be installed.
586+
The <replaceable>DIRECTORY</> argument specifies the
587+
root directory of the OpenSSL installation.
588+
</para>
589+
590+
<para>
591+
<filename>configure</> will check for the required header
592+
files and libraries to make sure that your OpenSSL
593+
installation is sufficient before proceeding.
594+
</para>
595+
</listitem>
596+
</varlistentry>
597+
580598
<varlistentry>
581599
<term>--enable-syslog</term>
582600
<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.38 2000/05/02 20:01:52 thomas Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.39 2000/08/29 04:15:43 momjian Exp $
33
-->
44

55
<chapter id="libpq-chapter">
@@ -177,6 +177,17 @@ PGconn *PQconnectdb(const char *conninfo)
177177
</para>
178178
</listitem>
179179
</varlistentry>
180+
181+
<varlistentry>
182+
<term><literal>requiressl</literal></term>
183+
<listitem>
184+
<para>
185+
Set to '1' to require SSL connection to the backend. Libpq
186+
will then refuse to connect if the server does not support
187+
SSL. Set to '0' (default) to negotiate with server.
188+
</para>
189+
</listitem>
190+
</varlistentry>
180191
</variablelist>
181192

182193
If any parameter is unspecified, then the corresponding
@@ -633,6 +644,25 @@ int PQbackendPID(const PGconn *conn);
633644
server host, not the local host!
634645
</para>
635646
</listitem>
647+
648+
<listitem>
649+
<para>
650+
<function>PQgetssl</function>
651+
Returns the SSL structure used in the connection, or NULL
652+
if SSL is not in use.
653+
<synopsis>
654+
SSL *PQgetssl(const PGconn *conn);
655+
</synopsis>
656+
This structure can be used to verify encryption levels, check
657+
server certificate and more. Refer to the OpenSSL documentation
658+
for information about this structure.
659+
</para>
660+
<para>
661+
You must define <literal>USE_SSL</literal> in order to get the
662+
prototype for this function. Doing this will also
663+
automatically include <filename>ssl.h</filename> from OpenSSL.
664+
</para>
665+
</listitem>
636666
</itemizedlist>
637667
</para>
638668
</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.21 2000/08/28 11:57:40 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.22 2000/08/29 04:15:43 momjian Exp $
33
-->
44

55
<Chapter Id="runtime">
@@ -1726,6 +1726,62 @@ perl: warning: Falling back to the standard locale ("C").
17261726
</para>
17271727
</sect1>
17281728

1729+
<sect1>
1730+
<title>Secure TCP/IP Connection with SSL</title>
1731+
1732+
<para>
1733+
PostgreSQL has native support for connections over SSL to encrypt
1734+
client/server communications for increased security. This requires
1735+
<productname>OpenSSL</productname> to be installed on both client
1736+
and server systems and support enabled at compile-time using
1737+
the configure script.
1738+
</para>
1739+
1740+
<para>
1741+
With SSL support compiled in, the Postgres backend can be
1742+
started with argument -l to enable SSL connections.
1743+
When starting in SSL mode, the postmaster will look for the
1744+
files <filename>server.key</filename> and
1745+
<filename>server.cert</filename> in the <envar>PGDATA</envar>
1746+
directory. These files should contain the server private key and
1747+
certificate respectively. If the private key is protected with a
1748+
passphrase, the postmaster will prompt for the passphrase and not
1749+
start until it has been provided.
1750+
</para>
1751+
1752+
<para>
1753+
The postmaster will listen for both standard and SSL connections
1754+
on the same TCP/IP port, and will negotiate with any connecting
1755+
client wether to use SSL or not. Use the <filename>pg_hba.conf</filename>
1756+
file to optionally require SSL in order to accept a connection.
1757+
</para>
1758+
1759+
<para>
1760+
For details on how to create your server private key and certificate,
1761+
refer to the OpenSSL documentation. A simple self-signed certificate
1762+
can be used to get started testing, but a certificate signed by a CA
1763+
(either one of the global CAs or a local one) should be used in
1764+
production so the client can verify the servers identity. To create
1765+
a quick self-signed certificate, use the <filename>CA.pl</filename>
1766+
script included in OpenSSL:
1767+
<programlisting>
1768+
CA.pl -newcert
1769+
</programlisting>
1770+
Fill out the information the script asks for. Make sure to enter
1771+
the local hostname as Common Name. The script will generate a key
1772+
which is passphrase protected. To remove the passphrase (required
1773+
if you want automatic startup of the postmaster), run the command
1774+
<programlisting>
1775+
openssl x509 -inform PEM -outform PEM -in newreq.pem -out newkey_no_passphrase.pem
1776+
</programlisting>
1777+
Enter the old passphrase to unlock the existing key. Copy the file
1778+
<filename>newreq.pem</filename> to <filename>PGDATA/server.cert</filename>
1779+
and <filename>newkey_no_passphrase.pem</filename> to
1780+
<filename>PGDATA/server.key</filename>. Remove the PRIVATE KEY part
1781+
from the <filename>server.cert</filename> using any text editor.
1782+
</para>
1783+
</sect1>
1784+
17291785
<sect1>
17301786
<title>Secure TCP/IP Connection with SSH</title>
17311787

0 commit comments

Comments
 (0)