Fix multiple breakages in our support for SSL certificates.

doc/src/sgml/libpq.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.163 2004/09/23 13:31:09 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.164 2004/09/26 22:51:49 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -233,22 +233,13 @@ PGconn *PQconnectdb(const char *conninfo);
 
       <para>
        If <productname>PostgreSQL</> is compiled without SSL support,
-       using option <literal>require</> will cause an error, and
+       using option <literal>require</> will cause an error, while
        options <literal>allow</> and <literal>prefer</> will be
        tolerated but <application>libpq</> will be unable to negotiate
        an <acronym>SSL</>
        connection.<indexterm><primary>SSL</><secondary
        sortas="libpq">with libpq</></indexterm>
       </para>
-
-      <para>
-       Please note that <acronym>SSL</> support in libpq covers
-       encryption only.  It will not verify the validity of the
-       certificate presented by the server that you are connecting to,
-       nor verify that the hostname matches that of the server's
-       certificate.  Additionally, there is no support for client
-       certificates.
-      </para>
      </listitem>
     </varlistentry>
 
@@ -3688,6 +3679,41 @@ If the permissions are less strict than this, the file will be ignored.
 </para>
 </sect1>
 
+
+<sect1 id="libpq-ssl">
+<title>SSL Support</title>
+
+<indexterm zone="libpq-ssl">
+ <primary>SSL</primary>
+</indexterm>
+
+  <para>
+   <productname>PostgreSQL</> has native support for using
+   <acronym>SSL</> connections to encrypt client/server communications
+   for increased security. See <xref linkend="ssl-tcp"> for details
+   about the server-side <acronym>SSL</> functionality.
+  </para>
+
+  <para>
+   If the server demands a 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, and must not be world-readable.
+  </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.  The SSL connection will
+   fail if the server does not present a certificate; therefore, to
+   use this feature the server must also have a <filename>root.crt</> file.
+  </para>
+</sect1>
+
+
 <sect1 id="libpq-threading">
 <title>Behavior in Threaded Programs</title>
 

doc/src/sgml/runtime.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.283 2004/09/23 13:15:57 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.284 2004/09/26 22:51:49 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -804,7 +804,7 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         Enables <acronym>SSL</> connections. Please read
         <xref linkend="ssl-tcp"> before using this. The default
-        is off.
+        is off.  This parameter can only be set at server start.
        </para>
       </listitem>
      </varlistentry>
@@ -4324,8 +4324,8 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
    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</>. See <xref
-   linkend="auth-pg-hba-conf"> about how to force the server to
-   require use of <acronym>SSL</> for certain connections.
+   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>
@@ -4361,20 +4361,24 @@ chmod og-rwx server.key
 
   <para>
    If verification of client certificates is required, place the
-   certificates of the <acronym>CA</acronym> you wish to check for in
+   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
-   making the connection and it must have been signed by one of the
-   certificates present in <filename>root.crt</filename>.  If no
-   certificate is presented, the connection will be allowed to proceed
-   anway.
+   during SSL connection startup, and it must have been signed by one of the
+   certificates present in <filename>root.crt</filename>.
   </para>
 
   <para>
-   The <filename>root.crt</filename> file is always checked for, and
-   its absence will be noted through a message in the log.  This is
-   merely an informative message that client certificates will not be
-   requested.
+   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>
+
+  <para>
+   The files <filename>server.key</>, <filename>server.crt</>,
+   and <filename>root.crt</filename> are only examined during server
+   start; so you must restart the server to make changes in them take
+   effect.
   </para>
  </sect1>