database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-02 11:44:50 +03:00
Code

Clarify usage of clientcert authentication option.

Browse Source 
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>
This commit is contained in:
Tom Lane 2016-07-16 14:12:44 -04:00
parent 99dd8b05aa
commit 745513c702
2 changed files with 39 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/src/sgml/client-auth.sgml
View File

@ -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">

29
doc/src/sgml/runtime.sgml
View File

@ -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>