Skip to content

Commit 08c37fd

Browse files
bmomjianbmomjian
committed
Add documentation section about preventing server spoofing.
Update SSL documention to be clearer about certificates, and restructure for clarity.
1 parent 4c1836d commit 08c37fd

File tree

2 files changed

+136
-90
lines changed

2 files changed

+136
-90
lines changed

‎doc/src/sgml/libpq.sgml

Lines changed: 27 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.248 2007/12/09 19:01:40 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.249 2007/12/25 04:00:43 momjian Exp $ -->
22

33
<chapter id="libpq">
44
<title><application>libpq</application> - C Library</title>
@@ -5151,16 +5151,33 @@ defaultNoticeProcessor(void *arg, const char *message)
51515151
</para>
51525152

51535153
<para>
5154-
If the server demands a client certificate,
5154+
To verify the server certificate is trustworthy, place certificates of
5155+
the certificate authorities (<acronym>CA</acronym>) you trust in the
5156+
file <filename>~/.postgresql/root.crt</> in the user's home directory.
5157+
(On Microsoft Windows the file is named
5158+
<filename>%APPDATA%\postgresql\root.crt</filename>.)
5159+
<application>libpq</application> will then verify that the server's
5160+
certificate is signed by one of the trusted certificate authorities.
5161+
The SSL connection will fail if the server does not present a trusted
5162+
certificate. Certificate Revocation List (CRL) entries are also checked
5163+
if the file <filename>~/.postgresql/root.crl</filename> exists
5164+
(<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
5165+
Windows).
5166+
</para>
5167+
5168+
<para>
5169+
If the server requests a trusted client certificate,
51555170
<application>libpq</application> will send the certificate stored in
5156-
file <filename>~/.postgresql/postgresql.crt</> within the user's home
5157-
directory. A matching private key file
5158-
<filename>~/.postgresql/postgresql.key</> must also be present, unless
5159-
the secret key for the certificate is stored in a hardware token, as
5160-
specified by <envar>PGSSLKEY</envar>. (On Microsoft Windows these
5161-
files are named <filename>%APPDATA%\postgresql\postgresql.crt</filename>
5162-
and <filename>%APPDATA%\postgresql\postgresql.key</filename>.) The
5163-
private key file must not be world-readable.
5171+
file <filename>~/.postgresql/postgresql.crt</> in the user's home
5172+
directory. The certificate must be signed by one of the certificate
5173+
authorities (<acronym>CA</acronym>) trusted by the server. A matching
5174+
private key file <filename>~/.postgresql/postgresql.key</> must also
5175+
be present, unless the secret key for the certificate is stored in a
5176+
hardware token, as specified by <envar>PGSSLKEY</envar>. (On Microsoft
5177+
Windows these files are named
5178+
<filename>%APPDATA%\postgresql\postgresql.crt</filename> and
5179+
<filename>%APPDATA%\postgresql\postgresql.key</filename>.) The private
5180+
key file must not be world-readable.
51645181
</para>
51655182

51665183
<para>
@@ -5175,20 +5192,6 @@ defaultNoticeProcessor(void *arg, const char *message)
51755192
the hardware token.
51765193
</para>
51775194

5178-
<para>
5179-
If the file <filename>~/.postgresql/root.crt</> is present in the user's
5180-
home directory, <application>libpq</application> will use the
5181-
certificate list stored therein to verify the server's certificate.
5182-
(On Microsoft Windows the file is named
5183-
<filename>%APPDATA%\postgresql\root.crt</filename>.) The SSL connection
5184-
will fail if the server does not present a certificate; therefore, to
5185-
use this feature the server must have a <filename>server.crt</> file.
5186-
Certificate Revocation List (CRL) entries are also checked if the file
5187-
<filename>~/.postgresql/root.crl</filename> exists
5188-
(<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
5189-
Windows).
5190-
</para>
5191-
51925195
<para>
51935196
If you are using <acronym>SSL</> inside your application (in addition
51945197
to inside <application>libpq</application>), you can use
@@ -5197,7 +5200,6 @@ defaultNoticeProcessor(void *arg, const char *message)
51975200
application.
51985201
</para>
51995202

5200-
52015203
</sect1>
52025204

52035205

‎doc/src/sgml/runtime.sgml

Lines changed: 109 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.394 2007/12/23 03:10:04 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.395 2007/12/25 04:00:44 momjian Exp $ -->
22

33
<chapter Id="runtime">
44
<title>Operating System Environment</title>
@@ -1373,6 +1373,42 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
13731373
</important>
13741374
</sect1>
13751375

1376+
<sect1 id="preventing-server-spoofing">
1377+
<title>Preventing Server Spoofing</title>
1378+
1379+
<indexterm zone="preventing-server-spoofing">
1380+
<primary>server spoofing</primary>
1381+
</indexterm>
1382+
1383+
<para>
1384+
While the server is running, it is not possible for a malicious user
1385+
to interfere with client/server communications. However, when the
1386+
server is down it is possible for a local user to spoof the normal
1387+
server by starting their own server. The spoof server could read
1388+
passwords and queries sent by clients, but could not return any data
1389+
because the <varname>PGDATA</> directory would still be secure because
1390+
of directory permissions. Spoofing is possible because any user can
1391+
start a database server; a client cannot identify an invalid server
1392+
unless it is specially configured.
1393+
</para>
1394+
1395+
<para>
1396+
The simplest way to prevent invalid servers for <literal>local</>
1397+
connections is to use a Unix domain socket directory (<xref
1398+
linkend="guc-unix-socket-directory">) that has write permission only
1399+
for a trusted local user. This prevents a malicious user from creating
1400+
their own socket file in that directory. For TCP connections the server
1401+
must accept only <literal>hostssl</> connections (<xref
1402+
linkend="auth-pg-hba-conf">) and have SSL
1403+
<filename>server.key</filename> (key) and
1404+
<filename>server.crt</filename> (certificate) files (<xref
1405+
linkend="ssl-tcp">). The TCP client must connect using
1406+
<literal>sslmode='require'</> (<xref linkend="libpq-connect">) and have
1407+
a <filename>~/.postgresql/root.crt</> SSL certificate (<xref
1408+
linkend="libpq-ssl">).
1409+
</para>
1410+
</sect1>
1411+
13761412
<sect1 id="encryption-options">
13771413
<title>Encryption Options</title>
13781414

@@ -1545,97 +1581,105 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
15451581
<productname>PostgreSQL</> server can be started with
15461582
<acronym>SSL</> enabled by setting the parameter
15471583
<xref linkend="guc-ssl"> to <literal>on</> in
1548-
<filename>postgresql.conf</>. When
1549-
starting in <acronym>SSL</> mode, the server will look for the
1550-
files <filename>server.key</> and <filename>server.crt</> in the
1551-
data directory, which must contain the server private key
1552-
and certificate, respectively. These files must be set up correctly
1553-
before an <acronym>SSL</>-enabled server can start. If the private key is
1554-
protected with a passphrase, the server will prompt for the
1555-
passphrase and will not start until it has been entered.
1584+
<filename>postgresql.conf</>. The server will listen for both standard
1585+
and <acronym>SSL</> connections on the same TCP port, and will negotiate
1586+
with any connecting client on whether to use <acronym>SSL</>. By
1587+
default, this is at the client's option; see <xref
1588+
linkend="auth-pg-hba-conf"> about how to set up the server to require
1589+
use of <acronym>SSL</> for some or all connections.
15561590
</para>
15571591

15581592
<para>
1559-
The server will listen for both standard and <acronym>SSL</>
1560-
connections on the same TCP port, and will negotiate with any
1561-
connecting client on whether to use <acronym>SSL</>. By default,
1562-
this is at the client's option; see <xref
1563-
linkend="auth-pg-hba-conf"> about how to set up the server to
1564-
require use of <acronym>SSL</> for some or all connections.
1593+
<productname>PostgreSQL</productname> reads the system-wide
1594+
<productname>OpenSSL</productname> configuration file. By default, this
1595+
file is named <filename>openssl.cnf</filename> and is located in the
1596+
directory reported by <literal>openssl version -d</>.
1597+
This default can be overridden by setting environment variable
1598+
<envar>OPENSSL_CONF</envar> to the name of the desired configuration file.
15651599
</para>
15661600

15671601
<para>
15681602
<productname>OpenSSL</productname> supports a wide range of ciphers
1569-
and authentication algorithms, whose strength varies significantly.
1570-
You can restrict the list of ciphers that can be used to connect to
1571-
your server by adjusting the <xref linkend="guc-ssl-ciphers"> parameter.
1603+
and authentication algorithms, of varying strength. While a list of
1604+
ciphers can be specified in the <productname>OpenSSL</productname>
1605+
configuration file, you can specify ciphers specifically for use by
1606+
the database server by modifying <xref linkend="guc-ssl-ciphers"> in
1607+
<filename>postgresql.conf</>.
15721608
</para>
15731609

15741610
<para>
1575-
<productname>PostgreSQL</productname> reads the system-wide
1576-
<productname>OpenSSL</productname> configuration file. By default, this
1577-
file is named <filename>openssl.cnf</filename> and is located in the
1578-
directory reported by <literal>openssl version -d</>.
1579-
This default can be overridden by setting environment variable
1580-
<envar>OPENSSL_CONF</envar> to the name of the desired configuration file.
1611+
To start in <acronym>SSL</> mode, the files <filename>server.crt</>
1612+
and <filename>server.key</> must exist in the server's data directory.
1613+
These files should contain the server certificate and private key,
1614+
respectively. If the private key is protected with a passphrase, the
1615+
server will prompt for the passphrase and will not start until it has
1616+
been entered.
1617+
</para>
1618+
1619+
<para>
1620+
To require the client to supply a trusted certificate, place
1621+
certificates of the certificate authorities (<acronym>CA</acronym>)
1622+
you trust in the file <filename>root.crt</filename> in the data
1623+
directory. A certificate will then be requested from the client during
1624+
SSL connection startup. (See <xref linkend="libpq-ssl"> for a
1625+
description of how to set up client certificates.) The server will
1626+
verify that the client's certificate is signed by one of the trusted
1627+
certificate authorities. Certificate Revocation List (CRL) entries
1628+
are also checked if the file <filename>root.crl</filename> exists.
1629+
</para>
1630+
1631+
<para>
1632+
If the <filename>root.crt</filename> file is not present, client
1633+
certificates will not be requested or checked. In this mode, SSL
1634+
provides encrypted communication but not authentication.
15811635
</para>
15821636

15831637
<para>
1584-
For details on how to create your server private key and certificate,
1585-
refer to the <productname>OpenSSL</> documentation. A
1586-
self-signed certificate can be used for testing, but a
1587-
certificate signed by a certificate authority (<acronym>CA</>)
1588-
(either one of the global
1589-
<acronym>CAs</> or a local one) should be used in production so the
1590-
client can verify the server's identity. To create a quick
1591-
self-signed certificate, use the following
1592-
<productname>OpenSSL</productname> command:
1638+
The files <filename>server.key</>, <filename>server.crt</>,
1639+
<filename>root.crt</filename>, and <filename>root.crl</filename>
1640+
are only examined during server start; so you must restart
1641+
the server for changes in them to take effect.
1642+
</para>
1643+
1644+
<sect2 id="ssl-certificate">
1645+
<title>Creating a Self-Signed Certificate</title>
1646+
1647+
<para>
1648+
To create a quick self-signed certificate for the server, use the
1649+
following <productname>OpenSSL</productname> command:
15931650
<programlisting>
15941651
openssl req -new -text -out server.req
15951652
</programlisting>
1596-
Fill out the information that <application>openssl</> asks for. Make sure
1597-
you enter the local host name as <quote>Common Name</>; the challenge
1598-
password can be left blank. The program will generate a key that is
1599-
passphrase protected; it will not accept a passphrase that is less
1600-
than four characters long. To remove the passphrase (as you must if
1601-
you want automatic start-up of the server), run the commands:
1653+
Fill out the information that <application>openssl</> asks for. Make sure
1654+
you enter the local host name as <quote>Common Name</>; the challenge
1655+
password can be left blank. The program will generate a key that is
1656+
passphrase protected; it will not accept a passphrase that is less
1657+
than four characters long. To remove the passphrase (as you must if
1658+
you want automatic start-up of the server), run the commands:
16021659
<programlisting>
16031660
openssl rsa -in privkey.pem -out server.key
16041661
rm privkey.pem
16051662
</programlisting>
1606-
Enter the old passphrase to unlock the existing key. Now do:
1663+
Enter the old passphrase to unlock the existing key. Now do:
16071664
<programlisting>
16081665
openssl req -x509 -in server.req -text -key server.key -out server.crt
16091666
chmod og-rwx server.key
16101667
</programlisting>
1611-
to turn the certificate into a self-signed certificate and to copy the
1612-
key and certificate to where the server will look for them.
1613-
</para>
1668+
to turn the certificate into a self-signed certificate and to copy
1669+
the key and certificate to where the server will look for them.
1670+
For more details on how to create your server private key and
1671+
certificate, refer to the <productname>OpenSSL</> documentation.
1672+
</para>
16141673

1615-
<para>
1616-
If verification of client certificates is required, place the
1617-
certificates of the <acronym>CA</acronym>(s) you wish to check for in
1618-
the file <filename>root.crt</filename> in the data directory. When
1619-
present, a client certificate will be requested from the client
1620-
during SSL connection startup, and it must have been signed by one of
1621-
the certificates present in <filename>root.crt</filename>. (See <xref
1622-
linkend="libpq-ssl"> for a description of how to set up client
1623-
certificates.) Certificate Revocation List (CRL) entries are also
1624-
checked if the file <filename>root.crl</filename> exists.
1625-
</para>
1674+
<para>
1675+
A self-signed certificate can be used for testing, but a certificate
1676+
signed by a certificate authority (<acronym>CA</>) (either one of the
1677+
global <acronym>CAs</> or a local one) should be used in production
1678+
so the client can verify the server's identity.
1679+
</para>
16261680

1627-
<para>
1628-
When the <filename>root.crt</filename> file is not present, client
1629-
certificates will not be requested or checked. In this mode, SSL
1630-
provides communication security but not authentication.
1631-
</para>
1681+
</sect2>
16321682

1633-
<para>
1634-
The files <filename>server.key</>, <filename>server.crt</>,
1635-
<filename>root.crt</filename>, and <filename>root.crl</filename>
1636-
are only examined during server start; so you must restart
1637-
the server to make changes in them take effect.
1638-
</para>
16391683
</sect1>
16401684

16411685
<sect1 id="ssh-tunnels">

0 commit comments

Comments
 (0)