From 0516c61b756e39ed6eb7a6bb54311a841002211a Mon Sep 17 00:00:00 2001 From: Magnus Hagander Date: Sat, 9 Mar 2019 12:09:10 -0800 Subject: Add new clientcert hba option verify-full This allows a login to require both that the cn of the certificate matches (like authentication type cert) *and* that another authentication method (such as password or kerberos) succeeds as well. The old value of clientcert=1 maps to the new clientcert=verify-ca, clientcert=0 maps to the new clientcert=no-verify, and the new option erify-full will add the validation of the CN. Author: Julian Markwort, Marius Timmer Reviewed by: Magnus Hagander, Thomas Munro --- doc/src/sgml/client-auth.sgml | 25 ++++++++++++-------- doc/src/sgml/runtime.sgml | 54 ++++++++++++++++++++++++++++++++----------- 2 files changed, 57 insertions(+), 22 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index c2114021c36..411f1e16794 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -563,10 +563,17 @@ hostnossl database user 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. + can be specified in any hostssl record. + This option can be set to verify-ca or + verify-full. Both options require the client + to present a valid (trusted) SSL certificate, while + verify-full additionally enforces that the + cn (Common Name) in the certificate matches + the username or an applicable mapping. + This behavior is similar to the cert authentication method + (see ) but enables pairing + the verification of client certificates with any authentication + method that supports hostssl entries. @@ -1865,11 +1872,11 @@ host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapse 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. + assumed to be verify-ca or verify-full, + 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 7de26e98ad8..d786ebfb71d 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2316,13 +2316,25 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 (CAs) you trust in a file in the data directory, set the parameter in postgresql.conf to the new file name, and add the - authentication option clientcert=1 to the appropriate + authentication option clientcert=verify-ca or + clientcert=verify-full 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. + of how to set up certificates on the client.) + + + + For a hostssl entry with + clientcert=verify-ca, the server will verify + that the client's certificate is signed by one of the trusted + certificate authorities. If clientcert=verify-full + is specified, the server will not only verify the certificate + chain, but it will also check whether the username or its mapping + matches the cn (Common Name) of the provided certificate. + Note that certificate chain validation is always ensured when the + cert authentication method is used + (see ). @@ -2341,18 +2353,34 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 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. + not specified or is set to no-verify, 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. + + + + There are two approaches to enforce that users provide a certificate during login. + + + + The first approach makes use of the cert authentication + method for hostssl entries in pg_hba.conf, + such that the certificate itself is used for authentication while also + providing ssl connection security. See for details. + (It is not necessary to specify any clientcert options + explicitly when using the cert authentication method.) + In this case, the cn (Common Name) provided in + the certificate is checked against the user name or an applicable mapping. - 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. (It is not necessary to - specify clientcert=1 explicitly when using - the cert authentication method.) + The second approach combines any authentication method for hostssl + entries with the verification of client certificates by setting the + clientcert authentication option to verify-ca + or verify-full. The former option only enforces that + the certificate is valid, while the latter also ensures that the + cn (Common Name) in the certificate matches + the user name or an applicable mapping. -- cgit v1.2.3