diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index fec498c19a8536cdaff7c8a770dd6d0c46d0cd10..be43ec7814ff8a173ce567b120ebb37a21640ff5 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.248 2007/12/09 19:01:40 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.249 2007/12/25 04:00:43 momjian Exp $ -->
<chapter id="libpq">
<title><application>libpq</application> - C Library</title>
@@ -5151,16 +5151,33 @@ defaultNoticeProcessor(void *arg, const char *message)
</para>
<para>
- If the server demands a client certificate,
+ To verify the server certificate is trustworthy, place certificates of
+ the certificate authorities (<acronym>CA</acronym>) you trust in the
+ file <filename>~/.postgresql/root.crt</> in the user's home directory.
+ (On Microsoft Windows the file is named
+ <filename>%APPDATA%\postgresql\root.crt</filename>.)
+ <application>libpq</application> will then verify that the server's
+ certificate is signed by one of the trusted certificate authorities.
+ The SSL connection will fail if the server does not present a trusted
+ certificate. Certificate Revocation List (CRL) entries are also checked
+ if the file <filename>~/.postgresql/root.crl</filename> exists
+ (<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
+ Windows).
+ </para>
+
+ <para>
+ If the server requests a trusted client certificate,
<application>libpq</application> will send the certificate stored in
- file <filename>~/.postgresql/postgresql.crt</> within the user's home
- directory. A matching private key file
- <filename>~/.postgresql/postgresql.key</> must also be present, unless
- the secret key for the certificate is stored in a hardware token, as
- specified by <envar>PGSSLKEY</envar>. (On Microsoft Windows these
- files are named <filename>%APPDATA%\postgresql\postgresql.crt</filename>
- and <filename>%APPDATA%\postgresql\postgresql.key</filename>.) The
- private key file must not be world-readable.
+ file <filename>~/.postgresql/postgresql.crt</> in the user's home
+ directory. The certificate must be signed by one of the certificate
+ authorities (<acronym>CA</acronym>) trusted by the server. A matching
+ private key file <filename>~/.postgresql/postgresql.key</> must also
+ be present, unless the secret key for the certificate is stored in a
+ hardware token, as specified by <envar>PGSSLKEY</envar>. (On Microsoft
+ Windows these files are named
+ <filename>%APPDATA%\postgresql\postgresql.crt</filename> and
+ <filename>%APPDATA%\postgresql\postgresql.key</filename>.) The private
+ key file must not be world-readable.
</para>
<para>
@@ -5175,20 +5192,6 @@ defaultNoticeProcessor(void *arg, const char *message)
the hardware token.
</para>
- <para>
- If the file <filename>~/.postgresql/root.crt</> is present in the user's
- home directory, <application>libpq</application> will use the
- certificate list stored therein to verify the server's certificate.
- (On Microsoft Windows the file is named
- <filename>%APPDATA%\postgresql\root.crt</filename>.) The SSL connection
- will fail if the server does not present a certificate; therefore, to
- use this feature the server must have a <filename>server.crt</> file.
- Certificate Revocation List (CRL) entries are also checked if the file
- <filename>~/.postgresql/root.crl</filename> exists
- (<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
- Windows).
- </para>
-
<para>
If you are using <acronym>SSL</> inside your application (in addition
to inside <application>libpq</application>), you can use
@@ -5197,7 +5200,6 @@ defaultNoticeProcessor(void *arg, const char *message)
application.
</para>
-
</sect1>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 1ba11602e8470359a4a8c43d715fde8f171a253c..b9f312daeda7f29b3e05a5650497bca03f8ef03b 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.394 2007/12/23 03:10:04 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.395 2007/12/25 04:00:44 momjian Exp $ -->
<chapter Id="runtime">
<title>Operating System Environment</title>
@@ -1373,6 +1373,42 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
</important>
</sect1>
+ <sect1 id="preventing-server-spoofing">
+ <title>Preventing Server Spoofing</title>
+
+ <indexterm zone="preventing-server-spoofing">
+ <primary>server spoofing</primary>
+ </indexterm>
+
+ <para>
+ While the server is running, it is not possible for a malicious user
+ to interfere with client/server communications. However, when the
+ server is down it is possible for a local user to spoof the normal
+ server by starting their own server. The spoof server could read
+ passwords and queries sent by clients, but could not return any data
+ because the <varname>PGDATA</> directory would still be secure because
+ of directory permissions. Spoofing is possible because any user can
+ start a database server; a client cannot identify an invalid server
+ unless it is specially configured.
+ </para>
+
+ <para>
+ The simplest way to prevent invalid servers for <literal>local</>
+ connections is to use a Unix domain socket directory (<xref
+ linkend="guc-unix-socket-directory">) that has write permission only
+ for a trusted local user. This prevents a malicious user from creating
+ their own socket file in that directory. For TCP connections the server
+ must accept only <literal>hostssl</> connections (<xref
+ linkend="auth-pg-hba-conf">) and have SSL
+ <filename>server.key</filename> (key) and
+ <filename>server.crt</filename> (certificate) files (<xref
+ linkend="ssl-tcp">). The TCP client must connect using
+ <literal>sslmode='require'</> (<xref linkend="libpq-connect">) and have
+ a <filename>~/.postgresql/root.crt</> SSL certificate (<xref
+ linkend="libpq-ssl">).
+ </para>
+ </sect1>
+
<sect1 id="encryption-options">
<title>Encryption Options</title>
@@ -1545,97 +1581,105 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<productname>PostgreSQL</> server can be started with
<acronym>SSL</> enabled by setting the parameter
<xref linkend="guc-ssl"> to <literal>on</> in
- <filename>postgresql.conf</>. When
- starting in <acronym>SSL</> mode, the server will look for the
- files <filename>server.key</> and <filename>server.crt</> in the
- data directory, which must contain the server private key
- and certificate, respectively. These files must be set up correctly
- before an <acronym>SSL</>-enabled server can start. If the private key is
- protected with a passphrase, the server will prompt for the
- passphrase and will not start until it has been entered.
+ <filename>postgresql.conf</>. The server will listen for both standard
+ and <acronym>SSL</> connections on the same TCP port, and will negotiate
+ with any connecting client on whether to use <acronym>SSL</>. By
+ default, this is at the client's option; see <xref
+ linkend="auth-pg-hba-conf"> about how to set up the server to require
+ use of <acronym>SSL</> for some or all connections.
</para>
<para>
- The server will listen for both standard and <acronym>SSL</>
- connections on the same TCP port, and will negotiate with any
- connecting client on whether to use <acronym>SSL</>. By default,
- this is at the client's option; see <xref
- linkend="auth-pg-hba-conf"> about how to set up the server to
- require use of <acronym>SSL</> for some or all connections.
+ <productname>PostgreSQL</productname> reads the system-wide
+ <productname>OpenSSL</productname> configuration file. By default, this
+ file is named <filename>openssl.cnf</filename> and is located in the
+ directory reported by <literal>openssl version -d</>.
+ This default can be overridden by setting environment variable
+ <envar>OPENSSL_CONF</envar> to the name of the desired configuration file.
</para>
<para>
<productname>OpenSSL</productname> supports a wide range of ciphers
- and authentication algorithms, whose strength varies significantly.
- You can restrict the list of ciphers that can be used to connect to
- your server by adjusting the <xref linkend="guc-ssl-ciphers"> parameter.
+ and authentication algorithms, of varying strength. While a list of
+ ciphers can be specified in the <productname>OpenSSL</productname>
+ configuration file, you can specify ciphers specifically for use by
+ the database server by modifying <xref linkend="guc-ssl-ciphers"> in
+ <filename>postgresql.conf</>.
</para>
<para>
- <productname>PostgreSQL</productname> reads the system-wide
- <productname>OpenSSL</productname> configuration file. By default, this
- file is named <filename>openssl.cnf</filename> and is located in the
- directory reported by <literal>openssl version -d</>.
- This default can be overridden by setting environment variable
- <envar>OPENSSL_CONF</envar> to the name of the desired configuration file.
+ To start in <acronym>SSL</> mode, the files <filename>server.crt</>
+ and <filename>server.key</> must exist in the server's data directory.
+ These files should contain the server certificate and private key,
+ respectively. If the private key is protected with a passphrase, the
+ server will prompt for the passphrase and will not start until it has
+ been entered.
+ </para>
+
+ <para>
+ To require the client to supply a trusted certificate, place
+ certificates of the certificate authorities (<acronym>CA</acronym>)
+ you trust in the file <filename>root.crt</filename> in the data
+ directory. A certificate will then be requested from the client during
+ SSL connection startup. (See <xref linkend="libpq-ssl"> for a
+ description of how to set up client certificates.) The server will
+ verify that the client's certificate is signed by one of the trusted
+ certificate authorities. Certificate Revocation List (CRL) entries
+ are also checked if the file <filename>root.crl</filename> exists.
+ </para>
+
+ <para>
+ If the <filename>root.crt</filename> file is not present, client
+ certificates will not be requested or checked. In this mode, SSL
+ provides encrypted communication but not authentication.
</para>
<para>
- For details on how to create your server private key and certificate,
- refer to the <productname>OpenSSL</> documentation. A
- self-signed certificate can be used for testing, but a
- certificate signed by a certificate authority (<acronym>CA</>)
- (either one of the global
- <acronym>CAs</> or a local one) should be used in production so the
- client can verify the server's identity. To create a quick
- self-signed certificate, use the following
- <productname>OpenSSL</productname> command:
+ The files <filename>server.key</>, <filename>server.crt</>,
+ <filename>root.crt</filename>, and <filename>root.crl</filename>
+ are only examined during server start; so you must restart
+ the server for changes in them to take effect.
+ </para>
+
+ <sect2 id="ssl-certificate">
+ <title>Creating a Self-Signed Certificate</title>
+
+ <para>
+ To create a quick self-signed certificate for the server, use the
+ following <productname>OpenSSL</productname> command:
<programlisting>
openssl req -new -text -out server.req
</programlisting>
- Fill out the information that <application>openssl</> asks for. Make sure
- you enter the local host name as <quote>Common Name</>; the challenge
- password can be left blank. The program will generate a key that is
- passphrase protected; it will not accept a passphrase that is less
- than four characters long. To remove the passphrase (as you must if
- you want automatic start-up of the server), run the commands:
+ Fill out the information that <application>openssl</> asks for. Make sure
+ you enter the local host name as <quote>Common Name</>; the challenge
+ password can be left blank. The program will generate a key that is
+ passphrase protected; it will not accept a passphrase that is less
+ than four characters long. To remove the passphrase (as you must if
+ you want automatic start-up of the server), run the commands:
<programlisting>
openssl rsa -in privkey.pem -out server.key
rm privkey.pem
</programlisting>
- Enter the old passphrase to unlock the existing key. Now do:
+ Enter the old passphrase to unlock the existing key. Now do:
<programlisting>
openssl req -x509 -in server.req -text -key server.key -out server.crt
chmod og-rwx server.key
</programlisting>
- to turn the certificate into a self-signed certificate and to copy the
- key and certificate to where the server will look for them.
- </para>
+ to turn the certificate into a self-signed certificate and to copy
+ the key and certificate to where the server will look for them.
+ For more details on how to create your server private key and
+ certificate, refer to the <productname>OpenSSL</> documentation.
+ </para>
- <para>
- If verification of client certificates is required, place the
- certificates of the <acronym>CA</acronym>(s) you wish to check for in
- the file <filename>root.crt</filename> in the data directory. When
- present, a client certificate will be requested from the client
- during SSL connection startup, and it must have been signed by one of
- the certificates present in <filename>root.crt</filename>. (See <xref
- linkend="libpq-ssl"> for a description of how to set up client
- certificates.) Certificate Revocation List (CRL) entries are also
- checked if the file <filename>root.crl</filename> exists.
- </para>
+ <para>
+ A self-signed certificate can be used for testing, but a certificate
+ signed by a certificate authority (<acronym>CA</>) (either one of the
+ global <acronym>CAs</> or a local one) should be used in production
+ so the client can verify the server's identity.
+ </para>
- <para>
- When the <filename>root.crt</filename> file is not present, client
- certificates will not be requested or checked. In this mode, SSL
- provides communication security but not authentication.
- </para>
+ </sect2>
- <para>
- The files <filename>server.key</>, <filename>server.crt</>,
- <filename>root.crt</filename>, and <filename>root.crl</filename>
- are only examined during server start; so you must restart
- the server to make changes in them take effect.
- </para>
</sect1>
<sect1 id="ssh-tunnels">