From 745513c70282180afd83c666e43bdb0b6fb8c688 Mon Sep 17 00:00:00 2001 From: Tom Lane 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 database user specify options for the authentication method. Details about which options are available for which authentication methods appear below. + + + In addition to the method-specific options listed below, there is one + method-independent authentication option clientcert, which + can be specified in any hostssl record. When set + to 1, this option requires the client to present a valid + (trusted) SSL certificate, in addition to the other requirements of the + authentication method. + @@ -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 cn (Common Name) attribute of the - certificate + the client provide a valid, trusted certificate. No password prompt + will be sent to the client. The cn (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 cn 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" + + + In a pg_hba.conf record specifying certificate + authentication, the authentication option clientcert is + assumed to be 1, and it cannot be turned off since a client + certificate is necessary for this method. What the cert + method adds to the basic clientcert certificate validity test + is a check that the cn attribute matches the database + user name. + 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 Using Client Certificates - + To require the client to supply a trusted certificate, place certificates of the certificate authorities (CAs) you trust in the file root.crt in the data directory, set the parameter in postgresql.conf to root.crt, - and set the clientcert parameter - to 1 on the appropriate hostssl line(s) in - pg_hba.conf. + and add the authentication option clientcert=1 to the + appropriate hostssl line(s) in pg_hba.conf. A certificate will then be requested from the client during SSL connection startup. (See 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 CAs appear in + certificate authorities. + + + + If intermediate CAs appear in root.crt, the file must also contain certificate chains to their root CAs. Certificate Revocation List (CRL) entries @@ -2214,12 +2217,12 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - The clientcert option in pg_hba.conf is - available for all authentication methods, but only for rows specified as - hostssl. When clientcert 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 clientcert authentication option is available for + all authentication methods, but only in pg_hba.conf lines + specified as hostssl. When clientcert 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. @@ -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 cert authentication method, so that the certificates control user authentication as well as providing connection security. - See for details. + See for details. (It is not necessary to + specify clientcert=1 explicitly when using + the cert authentication method.)