[Doc] Improve hostssl related descriptions and option presentation

From 5bd53027d5f1cbe9021c9b4f7abe3be5792589dd Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Thu, 1 Feb 2024 15:24:30 -0700
Subject: [PATCH] docs: improve hostssl related descriptions and option
 presentation

runtime.sgml discussion regarding SSL was repetitive with itself
and presented in a problematic order - with discussion about
setting up the server configuration happening before a broad
overview of what all of the moving parts are.  Put describing
the two approaches first, with links to the reference material,
and then discuss the implementation detail of a trusted root
certificate.

client-auth.sgml treatment of hostssl ssl auth options and
the cert auth method is confusing.  They are related and so
discuss them once, together.  The cert method page provides
a nice place to isolate these, in addition to a largely
repeated discussion on the runtime.sgml page which points
back to this one spot for the extra layer of details for,
in particular, the user mapping.

NOTES:

I left the "comparison is done with the DN in RFC"
paragraph content as-is though I think its presence or
content needs re-evaluation.

I moved the wording regarding "trust+clientcert" to
the runtime page as that material fits better in
overview than reference.  I also changed it from
words to an actual pg_hba.conf line; which seems
a bit out of place but going with it for now.

The method pages are all children of the pg_hba.conf
page so if you land on cert from the runtime page
going from their directly to pg_hba.conf, or
realizing that you are basically in a section
that only pertains to pg_hba.conf, is not that
obvious.  Seems like these pages should have
xrefs added to them giving that context and
linking back to pg_hba.conf directly.
---
 doc/src/sgml/client-auth.sgml | 106 ++++++++++++++++++----------------
 doc/src/sgml/runtime.sgml     |  87 ++++++++++++----------------
 2 files changed, 92 insertions(+), 101 deletions(-)

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 56747c0e36..638c8e7057 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -621,8 +621,9 @@ include_dir         <replaceable>directory</replaceable>
         <term><literal>cert</literal></term>
         <listitem>
          <para>
-          Authenticate using SSL client certificates. See
-          <xref linkend="auth-cert"/> for details.
+          Authenticate the hostssl connection attempt using only the SSL certificate.
+          See <xref linkend="auth-cert"/> for details regarding the auth-options
+          any hostssl connection line can specify.
          </para>
         </listitem>
        </varlistentry>
@@ -660,45 +661,15 @@ include_dir         <replaceable>directory</replaceable>
        After the <replaceable>auth-method</replaceable> field, there can be field(s) of
        the form <replaceable>name</replaceable><literal>=</literal><replaceable>value</replaceable> that
        specify options for the authentication method. Details about which
-       options are available for which authentication methods appear below.
+       options are available for which authentication methods appear on their
+       individual detail pages.
       </para>
 
       <para>
-       In addition to the method-specific options listed below, there is a
-       method-independent authentication option <literal>clientcert</literal>, which
-       can be specified in any <literal>hostssl</literal> record.
-       This option can be set to <literal>verify-ca</literal> or
-       <literal>verify-full</literal>. Both options require the client
-       to present a valid (trusted) SSL certificate, while
-       <literal>verify-full</literal> additionally enforces that the
-       <literal>cn</literal> (Common Name) in the certificate matches
-       the username or an applicable mapping.
-       This behavior is similar to the <literal>cert</literal> authentication
-       method (see <xref linkend="auth-cert"/>) but enables pairing
-       the verification of client certificates with any authentication
-       method that supports <literal>hostssl</literal> entries.
-      </para>
-      <para>
-       On any record using client certificate authentication (i.e. one
-       using the <literal>cert</literal> authentication method or one
-       using the <literal>clientcert</literal> option), you can specify
-       which part of the client certificate credentials to match using
-       the <literal>clientname</literal> option. This option can have one
-       of two values. If you specify <literal>clientname=CN</literal>, which
-       is the default, the username is matched against the certificate's
-       <literal>Common Name (CN)</literal>. If instead you specify
-       <literal>clientname=DN</literal> the username is matched against the
-       entire <literal>Distinguished Name (DN)</literal> of the certificate.
-       This option is probably best used in conjunction with a username map.
-       The comparison is done with the <literal>DN</literal> in
-       <ulink url="https://tools.ietf.org/html/rfc2253">RFC 2253</ulink>
-       format. To see the <literal>DN</literal> of a client certificate
-       in this format, do
-<programlisting>
-openssl x509 -in myclient.crt -noout -subject -nameopt RFC2253 | sed "s/^subject=//"
-</programlisting>
-        Care needs to be taken when using this option, especially when using
-        regular expression matching against the <literal>DN</literal>.
+       The <literal>hostssl</literal> connection type, in addition to allowing any
+       authentication-method-specific options, allows the
+       <literal>auth-options</literal> detailed in <xref linkend="auth-cert"/> for
+       the <literal>cert</literal> authentication method.
       </para>
      </listitem>
     </varlistentry>
@@ -2170,24 +2141,53 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
     This authentication method uses SSL client certificates to perform
     authentication. It is therefore only available for SSL connections;
     see <xref linkend="ssl-openssl-config"/> for SSL configuration instructions.
-    When using this authentication method, the server will require that
-    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.
+    When using this (<literal>cert</literal>) authentication method,
+    the server will require that the client provide a valid, trusted certificate,
+    containing their certificate name in either the <literal>Common Name (CN)</literal>
+    or <literal>Distinguished Name (DN)</literal> as specifed by the
+    <literal>clientname</literal> option.  User name mapping can be used to allow
+    certificate name to be different from the database user name.
+   </para>
+
+   <para>
+    SSL connections using some other authentication method will not, by default,
+    look for or use a client certificate.  The <literal>clientcert</literal>
+    option can be added to the <literal>auth-options</literal> to also require
+    and optionally use a client certificate.
    </para>
 
    <para>
     The following configuration options are supported for SSL certificate
     authentication:
     <variablelist>
+     <varlistentry>
+      <term><literal>clientcert</literal></term>
+      <listitem>
+       <para>
+        Enables requiring a client certificate be present on the SSL connection.
+        Values of <literal>verify-ca</literal> and <literal>verify-full</literal>,
+        specify <literal>verify-full</literal> to include certificate name extraction
+        and verification.  The authentication method <literal>host</literal> applies
+        a non-overrideable value of <literal>verify-full</literal> for this option.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term><literal>clientname</literal></term>
+      <listitem>
+       <para>
+        Under <literal>verify-full</literal> this specifies where to obtain the certificate name.
+        Values of <literal>CN</literal> and <literal>DN</literal> are allowed, matching
+        the Common Name and Distinguished Name on the certificate respectively.  The default
+        value is <literal>CN</literal>
+       </para>
+      </listitem>
+     </varlistentry>
      <varlistentry>
       <term><literal>map</literal></term>
       <listitem>
        <para>
-        Allows for mapping between system and database user names. See
+        Allows for mapping between certificate and database user names. See
         <xref linkend="auth-username-maps"/> for details.
        </para>
       </listitem>
@@ -2196,11 +2196,17 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
    </para>
 
    <para>
-    It is redundant to use the <literal>clientcert</literal> option with
-    <literal>cert</literal> authentication because <literal>cert</literal>
-    authentication is effectively <literal>trust</literal> authentication
-    with <literal>clientcert=verify-full</literal>.
+    The comparison is done with the <literal>DN</literal> in
+    <ulink url="https://tools.ietf.org/html/rfc2253">RFC 2253</ulink>
+    format. To see the <literal>DN</literal> of a client certificate
+    in this format, do
+<programlisting>
+openssl x509 -in myclient.crt -noout -subject -nameopt RFC2253 | sed "s/^subject=//"
+</programlisting>
+    Care needs to be taken when using this option, especially when using
+    regular expression matching against the <literal>DN</literal>.
    </para>
+
   </sect1>
 
   <sect1 id="auth-pam">
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 64753d9c01..9e4bede7d0 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2330,62 +2330,17 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    <title>Using Client Certificates</title>
 
   <para>
-   To require the client to supply a trusted certificate,
-   place certificates of the root certificate authorities
-   (<acronym>CA</acronym>s) you trust in a file in the data
-   directory, set the parameter <xref linkend="guc-ssl-ca-file"/> in
-   <filename>postgresql.conf</filename> to the new file name, and add the
-   authentication option <literal>clientcert=verify-ca</literal> or
-   <literal>clientcert=verify-full</literal> to the appropriate
-   <literal>hostssl</literal> line(s) in <filename>pg_hba.conf</filename>.
-   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.)
-  </para>
-
-  <para>
-   For a <literal>hostssl</literal> entry with
-   <literal>clientcert=verify-ca</literal>, the server will verify
-   that the client's certificate is signed by one of the trusted
-   certificate authorities. If <literal>clientcert=verify-full</literal>
-   is specified, the server will not only verify the certificate
-   chain, but it will also check whether the username or its mapping
-   matches the <literal>cn</literal> (Common Name) of the provided certificate.
-   Note that certificate chain validation is always ensured when the
-   <literal>cert</literal> authentication method is used
-   (see <xref linkend="auth-cert"/>).
-  </para>
-
-  <para>
-   Intermediate certificates that chain up to existing root certificates
-   can also appear in the <xref linkend="guc-ssl-ca-file"/> file if
-   you wish to avoid storing them on clients (assuming the root and
-   intermediate certificates were created with <literal>v3_ca</literal>
-   extensions).  Certificate Revocation List (CRL) entries are also
-   checked if the parameter <xref linkend="guc-ssl-crl-file"/> or
-   <xref linkend="guc-ssl-crl-dir"/> is set.
-  </para>
-
-  <para>
-   The <literal>clientcert</literal> authentication option is available for
-   all authentication methods, but only in <filename>pg_hba.conf</filename> lines
-   specified as <literal>hostssl</literal>.  When <literal>clientcert</literal> is
-   not specified, the server verifies the client certificate against its CA
-   file only if a client certificate is presented and the CA is configured.
-  </para>
-
-  <para>
-   There are two approaches to enforce that users provide a certificate during login.
+   There are two approaches to enforce that users provide an SSL certificate during login.
   </para>
 
   <para>
    The first approach makes use of the <literal>cert</literal> authentication
    method for <literal>hostssl</literal> entries in <filename>pg_hba.conf</filename>,
-   such that the certificate itself is used for authentication while also
-   providing ssl connection security. See <xref linkend="auth-cert"/> for details.
-   (It is not necessary to specify any <literal>clientcert</literal> options
+   (see <xref linkend="auth-pg-hba-conf"/>) such that the certificate itself
+   is used for authentication while also providing ssl connection security.
+   (It is not necessary to specify the <literal>clientcert</literal> option
    explicitly when using the <literal>cert</literal> authentication method.)
-   In this case, the <literal>cn</literal> (Common Name) provided in
+   By default, the <literal>cn</literal> (Common Name) provided in
    the certificate is checked against the user name or an applicable mapping.
   </para>
 
@@ -2394,10 +2349,40 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    entries with the verification of client certificates by setting the
    <literal>clientcert</literal> authentication option to <literal>verify-ca</literal>
    or <literal>verify-full</literal>. The former option only enforces that
-   the certificate is valid, while the latter also ensures that the
+   the certificate is valid, while the latter also ensures that, by default, the
    <literal>cn</literal> (Common Name) in the certificate matches
    the user name or an applicable mapping.
   </para>
+
+  <para>
+   As the first approach is really just a special case of the second, the reference
+   documentation for both is detailed in the same place, <xref linkend="auth-cert"/>.
+   Specifically, the <literal>cert</literal> authentication method is equivalent to:
+<programlisting>
+hostssl DATABASE USER IP trust clientcert=verify-full
+</programlisting>
+  </para>
+
+  <para>
+   Verifying client-supplied certificates requires that certificates of the
+   trusted root certificate authorities (<acronym>CA</acronym>s) exist in a
+   file in the data directory.  Set the parameter
+   <xref linkend="guc-ssl-ca-file"/> in
+   <filename>postgresql.conf</filename> to this file name.
+   (See <xref linkend="libpq-ssl"/> for a description
+   of how to set up certificates on the client.)
+  </para>
+
+  <para>
+   Intermediate certificates that chain up to existing root certificates
+   can also appear in the <xref linkend="guc-ssl-ca-file"/> file if
+   you wish to avoid storing them on clients (assuming the root and
+   intermediate certificates were created with <literal>v3_ca</literal>
+   extensions).  Certificate Revocation List (CRL) entries are also
+   checked if the parameter <xref linkend="guc-ssl-crl-file"/> or
+   <xref linkend="guc-ssl-crl-dir"/> is set.
+  </para>
+
   </sect2>
 
   <sect2 id="ssl-server-files">
-- 
2.34.1