Clarify usage of clientcert authentication option.

For some reason this option wasn't discussed at all in client-auth.sgml.
Document it there, and be more explicit about its relationship to the
"cert" authentication method.  Per gripe from Srikanth Venkatesh.

I failed to resist the temptation to do some minor wordsmithing in the
same area, too.

Discussion: <20160713110357[email protected]>

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 1d0f0409a051ceeb1a1aceec39f2256490ced1a2..ca262d945237045a8d8a227a357ebe875a2dd1a6 100644 (file)
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -547,6 +547,15 @@ hostnossl  database  user
        specify options for the authentication method. Details about which
        options are available for which authentication methods appear below.
       
+
+      
+       In addition to the method-specific options listed below, there is one
+       method-independent authentication option clientcert, which
+       can be specified in any hostssl record.  When set
+       to 1, this option requires the client to present a valid
+       (trusted) SSL certificate, in addition to the other requirements of the
+       authentication method.
+      
      
     
    
@@ -1632,9 +1641,9 @@ host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub"
     This authentication method uses SSL client certificates to perform
     authentication. It is therefore only available for SSL connections.
     When using this authentication method, the server will require that
-    the client provide a valid certificate. No password prompt will be sent
-    to the client. The cn (Common Name) attribute of the
-    certificate
+    the client provide a valid, trusted certificate.  No password prompt
+    will be sent to the client.  The cn (Common Name)
+    attribute of the certificate
     will be compared to the requested database user name, and if they match
     the login will be allowed.  User name mapping can be used to allow
     cn to be different from the database user name.
@@ -1655,6 +1664,16 @@ host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub"
      
     
    
+
+   
+    In a pg_hba.conf record specifying certificate
+    authentication, the authentication option clientcert is
+    assumed to be 1, and it cannot be turned off since a client
+    certificate is necessary for this method.  What the cert
+    method adds to the basic clientcert certificate validity test
+    is a check that the cn attribute matches the database
+    user name.
+   
   
 
   

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 90def00ffcbc9798cff073e86cde1aa8067f8bb5..e3e254b3dcaa339a37f59b38a1ae8ca4ac67843a 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2189,20 +2189,23 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
   
    Using Client Certificates
 
-   
+  
    To require the client to supply a trusted certificate, place
    certificates of the certificate authorities (CAs)
    you trust in the file root.crt in the data
    directory, set the parameter  in
    postgresql.conf to root.crt,
-   and set the clientcert parameter
-   to 1 on the appropriate hostssl line(s) in
-   pg_hba.conf.
+   and add the authentication option clientcert=1 to the
+   appropriate hostssl line(s) in pg_hba.conf.
    A certificate will then be requested from the client during
    SSL connection startup.  (See  for a
    description of how to set up certificates on the client.)  The server will
    verify that the client's certificate is signed by one of the trusted
-   certificate authorities.  If intermediate CAs appear in
+   certificate authorities.
+  
+
+  
+   If intermediate CAs appear in
    root.crt, the file must also contain certificate
    chains to their root CAs.  Certificate Revocation List
    (CRL) entries
@@ -2214,12 +2217,12 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
   
 
   
-   The clientcert option in pg_hba.conf is
-   available for all authentication methods, but only for rows specified as
-   hostssl.  When clientcert is not specified
-   or is set to 0, the server will still verify presented client
-   certificates against its CA list, if one is configured,
-   — but it will not insist that a client certificate be presented.
+   The clientcert authentication option is available for
+   all authentication methods, but only in pg_hba.conf lines
+   specified as hostssl.  When clientcert is
+   not specified or is set to 0, the server will still verify any presented
+   client certificates against its CA file, if one is configured — but
+   it will not insist that a client certificate be presented.
   
 
   
@@ -2234,7 +2237,9 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    If you are setting up client certificates, you may wish to use
    the cert authentication method, so that the certificates
    control user authentication as well as providing connection security.
-   See  for details.
+   See  for details.  (It is not necessary to
+   specify clientcert=1 explicitly when using
+   the cert authentication method.)