From c89404edf3f3b35a4a599d71f407055bda8261b6 Mon Sep 17 00:00:00 2001
From: Magnus Hagander <magnus@hagander.net>
Date: Thu, 13 Nov 2008 09:45:25 +0000
Subject: Fix libpq certificate validation for SSL connections.

Add config parameter "sslverify" to control the verification. Default
is to do full verification.

Clean up some old SSL code that never really worked.
---
 doc/src/sgml/libpq.sgml   | 53 +++++++++++++++++++++++++++++++++++++++++++----
 doc/src/sgml/runtime.sgml | 16 +++++++-------
 2 files changed, 58 insertions(+), 11 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 6f977f9083e..0b220ab514b 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.268 2008/11/09 00:28:34 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.269 2008/11/13 09:45:24 mha Exp $ -->
 
 <chapter id="libpq">
  <title><application>libpq</application> - C Library</title>
@@ -259,6 +259,33 @@
          </listitem>
         </varlistentry>
 
+        <varlistentry>
+         <term><literal>sslverify</literal></term>
+         <listitem>
+          <para>
+           This option controls how libpq verifies the certificate on the
+           server when performing an <acronym>SSL</> connection. There are
+           three options: <literal>none</> disables verification completely
+           (not recommended!); <literal>cert</> enables verification that
+           the certificate chains to a known CA only; <literal>cn</> will
+           both verify that the certificate chains to a known CA and that
+           the <literal>cn</> attribute of the certificate matches the
+           hostname the connection is being made to (default).
+          </para>
+
+          <para>
+           It is always recommended to use the <literal>cn</> value for
+           this parameter, since this is the only option that prevents
+           man-in-the-middle attacks. Note that this requires the server
+           name on the certificate to match exactly with the host name
+           used for the connection, and therefore does not support connections
+           to aliased names. It can be used with pure IP address connections
+           only if the certificate also has just the IP address in the
+           <literal>cn</> field.
+          </para>
+         </listitem>
+        </varlistentry>
+
         <varlistentry>
          <term><literal>requiressl</literal></term>
          <listitem>
@@ -5679,6 +5706,22 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
      </para>
     </listitem>
 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGSSLVERIFY</envar></primary>
+      </indexterm>
+      <envar>PGSSLVERIFY</envar> controls how libpq verifies the certificate on the
+       server when performing an <acronym>SSL</> connection. There are
+       three options: <literal>none</> disables verification completely
+       (not recommended!); <literal>cert</> enables verification that
+       the certificate chains to a known CA only; <literal>cn</> will
+       both verify that the certificate chains to a known CA and that
+       the <literal>cn</> attribute of the certificate matches the
+       hostname the connection is being made to (default).
+     </para>
+    </listitem>
+
     <listitem>
      <para>
       <indexterm>
@@ -6026,9 +6069,11 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
   </para>
 
   <para>
-   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.
+   When the <literal>sslverify</> parameter is set to <literal>cn</> or
+   <literal>cert</>, libpq will verify that the server certificate is
+   trustworthy by checking the certificate chain up to a <acronym>CA</>.
+   For this to work, place the certificate of a trusted <acronym>CA</>
+   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
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index a46f59cf1fc..b04de288c33 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.419 2008/11/04 04:18:50 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.420 2008/11/13 09:45:24 mha Exp $ -->
 
 <chapter Id="runtime">
  <title>Operating System Environment</title>
@@ -1418,9 +1418,9 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
    <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">).
+   <literal>sslmode='require'</>, specify <literal>sslverify='cn'</>
+   or <literal>sslverify='cert'</> and have the required certificate
+   files present (<xref linkend="libpq-connect">).
   </para>
  </sect1>
   
@@ -1544,8 +1544,8 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
 
    <listitem>
     <para> 
-     It is possible for both the client and server to provide SSL keys
-     or certificates to each other. It takes some extra configuration
+     It is possible for both the client and server to provide SSL
+     certificates to each other. It takes some extra configuration
      on each side, but this provides stronger verification of identity
      than the mere use of passwords. It prevents a computer from
      pretending to be the server just long enough to read the password
@@ -1757,7 +1757,9 @@ chmod og-rwx server.key
     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.
+    so the client can verify the server's identity. If all the clients
+    are local to the organization, using a local <acronym>CA</> is
+    recommended.
    </para>
 
   </sect2>
-- 
cgit v1.2.3