From ba1dfcec9624d12f008e4e2d27a40a2d18b8479c Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 14 Jul 2010 17:10:03 +0000
Subject: Allow full SSL certificate verification (wherein libpq checks its
 host name parameter against server cert's CN field) to succeed in the case
 where both host and hostaddr are specified.  As with the existing precedents
 for Kerberos, GSSAPI, SSPI, it is the calling application's responsibility
 that host and hostaddr match up --- we just use the host name as given. Per
 bug #5559 from Christopher Head.

In passing, make the error handling and messages for the no-host-name-given
failure more consistent among these four cases, and correct a lie in the
documentation: we don't attempt to reverse-lookup host from hostaddr
if host is missing.

Back-patch to 8.4 where SSL cert verification was introduced.
---
 doc/src/sgml/libpq.sgml | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index b0e60937c2c..08f7525fb33 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.289.2.2 2010/06/17 16:03:36 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.289.2.3 2010/07/14 17:10:02 tgl Exp $ -->
 
 <chapter id="libpq">
  <title><application>libpq</application> - C Library</title>
@@ -157,22 +157,26 @@
 
           <para>
            Using <literal>hostaddr</> instead of <literal>host</> allows the
-           application to avoid a host name look-up, which might be important in
-           applications with time constraints. However, Kerberos and GSSAPI authentication
-           requires the host name. The following therefore applies: If
-           <literal>host</> is specified without <literal>hostaddr</>, a host name
-           lookup occurs. If <literal>hostaddr</> is specified without
-           <literal>host</>, the value for <literal>hostaddr</> gives the remote
-           address. When Kerberos is used, a reverse name query occurs to obtain
-           the host name for Kerberos. If both
-           <literal>host</> and <literal>hostaddr</> are specified, the value for
-           <literal>hostaddr</> gives the remote address; the value for
-           <literal>host</> is ignored, unless Kerberos is used, in which case that
-           value is used for Kerberos authentication. (Note that authentication is
-           likely to fail if <application>libpq</application> is passed a host name
-           that is not the name of the machine at <literal>hostaddr</>.)  Also,
-           <literal>host</> rather than <literal>hostaddr</> is used to identify
-           the connection in <filename>~/.pgpass</> (see
+           application to avoid a host name look-up, which might be important
+           in applications with time constraints. However, a host name is
+           required for Kerberos, GSSAPI, or SSPI authentication, as well as
+           for full SSL certificate verification. The following rules are
+           used:
+           If <literal>host</> is specified without <literal>hostaddr</>,
+           a host name lookup occurs.
+           If <literal>hostaddr</> is specified without <literal>host</>,
+           the value for <literal>hostaddr</> gives the server address.
+           The connection attempt will fail in any of the cases where a
+           host name is required.
+           If both <literal>host</> and <literal>hostaddr</> are specified,
+           the value for <literal>hostaddr</> gives the server address.
+           The value for <literal>host</> is ignored unless needed for
+           authentication or verification purposes, in which case it will be
+           used as the host name.  Note that authentication is likely to fail
+           if <literal>host</> is not the name of the machine at
+           <literal>hostaddr</>.
+           Also, note that <literal>host</> rather than <literal>hostaddr</>
+           is used to identify the connection in <filename>~/.pgpass</> (see
            <xref linkend="libpq-pgpass">).
           </para>
 
-- 
cgit v1.2.3