From 745513c70282180afd83c666e43bdb0b6fb8c688 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 16 Jul 2016 14:12:44 -0400
Subject: [PATCH] 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>
---
doc/src/sgml/client-auth.sgml | 25 ++++++++++++++++++++++---
doc/src/sgml/runtime.sgml | 29 +++++++++++++++++------------
2 files changed, 39 insertions(+), 15 deletions(-)
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 1d0f0409a05..ca262d94523 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/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">
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 90def00ffcb..e3e254b3dca 100644
--- 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
<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,
- — 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 — 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>
--
GitLab