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.1410.30407@wrigleys.postgresql.org>

Author: tglsfdc

doc/src/sgml/client-auth.sgml

@@ -547,6 +547,15 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
        specify options for the authentication method. Details about which
        options are available for which authentication methods appear below.
       </para>
+
+      <para>
+       In addition to the method-specific options listed below, there is one
+       method-independent authentication option <literal>clientcert</>, which
+       can be specified in any <literal>hostssl</> record.  When set
+       to <literal>1</>, this option requires the client to present a valid
+       (trusted) SSL certificate, in addition to the other requirements of the
+       authentication method.
+      </para>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -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 <literal>cn</literal> (Common Name) attribute of the
-    certificate
+    the client provide a valid, trusted certificate.  No password prompt
+    will be sent to the client.  The <literal>cn</literal> (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
     <literal>cn</literal> 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"
      </varlistentry>
     </variablelist>
    </para>
+
+   <para>
+    In a <filename>pg_hba.conf</> record specifying certificate
+    authentication, the authentication option <literal>clientcert</> is
+    assumed to be <literal>1</>, and it cannot be turned off since a client
+    certificate is necessary for this method.  What the <literal>cert</>
+    method adds to the basic <literal>clientcert</> certificate validity test
+    is a check that the <literal>cn</literal> attribute matches the database
+    user name.
+   </para>
   </sect2>
 
   <sect2 id="auth-pam">

doc/src/sgml/runtime.sgml

@@ -2189,20 +2189,23 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
   <sect2 id="ssl-client-certificates">
    <title>Using Client Certificates</title>
 
-   <para>
+  <para>
    To require the client to supply a trusted certificate, place
    certificates of the certificate authorities (<acronym>CA</acronym>s)
    you trust in the file <filename>root.crt</filename> in the data
    directory, set the parameter <xref linkend="guc-ssl-ca-file"> in
    <filename>postgresql.conf</filename> to <literal>root.crt</literal>,
-   and set the <literal>clientcert</literal> parameter
-   to 1 on the appropriate <literal>hostssl</> line(s) in
-   <filename>pg_hba.conf</>.
+   and add the authentication option <literal>clientcert=1</literal> to the
+   appropriate <literal>hostssl</> line(s) in <filename>pg_hba.conf</>.
    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 certificates on the client.)  The server will
    verify that the client's certificate is signed by one of the trusted
-   certificate authorities.  If intermediate <acronym>CA</>s appear in
+   certificate authorities.
+  </para>
+
+  <para>
+   If intermediate <acronym>CA</>s appear in
    <filename>root.crt</filename>, the file must also contain certificate
    chains to their root <acronym>CA</>s.  Certificate Revocation List
    (CRL) entries
@@ -2214,12 +2217,12 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
   </para>
 
   <para>
-   The <literal>clientcert</literal> option in <filename>pg_hba.conf</> is
-   available for all authentication methods, but only for rows specified as
-   <literal>hostssl</>.  When <literal>clientcert</literal> is not specified
-   or is set to 0, the server will still verify presented client
-   certificates against its CA list, if one is configured,
-   &mdash; but it will not insist that a client certificate be presented.
+   The <literal>clientcert</literal> authentication option is available for
+   all authentication methods, but only in <filename>pg_hba.conf</> lines
+   specified as <literal>hostssl</>.  When <literal>clientcert</literal> 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 &mdash; but
+   it will not insist that a client certificate be presented.
   </para>
 
   <para>
@@ -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 <literal>cert</> authentication method, so that the certificates
    control user authentication as well as providing connection security.
-   See <xref linkend="auth-cert"> for details.
+   See <xref linkend="auth-cert"> for details.  (It is not necessary to
+   specify <literal>clientcert=1</literal> explicitly when using
+   the <literal>cert</> authentication method.)
   </para>
   </sect2>