Add documentation section about preventing server spoofing.

Update SSL documention to be clearer about certificates, and restructure
for clarity.

doc/src/sgml/libpq.sgml

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

doc/src/sgml/runtime.sgml

-<!-- $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">