diff options
| -rw-r--r-- | doc/src/sgml/client-auth.sgml | 25 | ||||
| -rw-r--r-- | 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> |