diff --git a/data/settings.js b/data/settings.js index c2450e037..f09b7737b 100644 --- a/data/settings.js +++ b/data/settings.js @@ -10265,6 +10265,17 @@ The most common choices are \`commonName\` and \`x500UniqueIdentifier\`. Note: [[setting,auth_ssl_username_from_cert]] MUST be enabled.` }, + ssl_peer_certificate_fingerprint_hash: { + default: '', + seealso: [ 'ssl', '[[link,ssl_configuration]]', '[[link,passdb_check_client_fp]]' ], + values: setting_types.STRING, + text: ` +An OpenSSL digest algorithm name to use to hash peer certificate names. +Setting this value enables \`ssl_client_cert_fp\` and \`ssl_client_cert_pubkey_fp\` +availability in [[setting,login_log_format_elements]] and also in authentication +variables. Weak algorithms are explicitly blacklisted, such as MD5.`, + }, + ssl_cipher_list: { default: 'ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@STRENGTH (for ssl_server, empty for ssl_client)', seealso: [ 'ssl', 'ssl_cipher_suites', 'ssl_min_protocol', '[[link,ssl_configuration]]' ], @@ -10553,10 +10564,15 @@ Renamed from \`ssl_verify_client_cert\` setting.` 'auth_ssl_require_client_cert', '[[link,ssl_configuration]]', ], - values: setting_types.BOOLEAN, + values: setting_types.ENUM, + values_enum: ['no', 'yes', 'any-cert'], text: ` If enabled, the imap/pop3/etc. client is requested to send an SSL certificate. +You can accept any certificate with \'any-cert\' value, but you must configure +authentication to check the client certificate with [[link,passdb_check_client_fp,check_client_fp]] (or +variant) extra field. See [[link,passdb_check_client_fp]]. + Note: This setting doesn't yet require the certificate to be valid or to even exist. See [[setting,auth_ssl_require_client_cert]].` }, diff --git a/docs/core/config/auth/passdb.md b/docs/core/config/auth/passdb.md index bc941f216..0914c09ce 100644 --- a/docs/core/config/auth/passdb.md +++ b/docs/core/config/auth/passdb.md @@ -18,6 +18,9 @@ dovecotlinks: passdb_result_values: hash: result-values text: "passdb: Result Values" + passdb_check_client_fp: + hash: check-client-fp + text: "passdb: check_client_fp Extra field" --- # Password Databases (`passdb`) @@ -442,6 +445,39 @@ a load spike of everybody getting logged in at exactly the same time. Do not perform any authentication, just store extra fields if user is found. +##### `check_client_fp` + +Match client certificate or public key fingerprint. + +Requires configuring [[setting,ssl_peer_certificate_fingerprint_hash]], [[setting,auth_ssl_require_client_cert]], +and [[setting,ssl_server_request_client_cert]] to require a client cert. + +This is intended to replace CA certificates with verifying client certificates using fingerprints, or to enforce +that particular public key is being used. If you are using CA certificates, +you can only fail authentication if the value is non-empty and does not match. If CA certificates are not used, then +if no passdb matches the fingerprint, then authentication is failed. + +The failure is per-passdb, so next passdb can continue authenticating the user. + +::warning If CA certificates are not used, a passdb must provide a valid check_client_fp (or variant) to validate the + client certificate. If none is provided, the authentication will fail. + +##### `check_client_cert_fp` + +Match client certificate fingerprint. See [[setting,ssl_peer_certificate_fingerprint_hash]]. + +Certificate fingerprint is calculated by taking hash value of DER encoded X509 client certificate. + +See [[link,passdb_check_client_fp]] + +##### `check_client_pubkey_fp +` +Match client public key fingerprint (but not certificate). See [[setting,ssl_peer_certificate_fingerprint_hash]]. + +Public key fingerprint is calculated by taking hash value of DER encoded certificate public key. + +See [[link,passdb_check_client_fp]] + #### `forward_` In a proxy, pass the variable to the next hop (backend) as diff --git a/docs/core/settings/variables.md b/docs/core/settings/variables.md index 3a291fbb6..f66e2153f 100644 --- a/docs/core/settings/variables.md +++ b/docs/core/settings/variables.md @@ -287,6 +287,8 @@ See also: | `ssl_security` | TLS session security string. If HAProxy is configured and it terminated the TLS connection, contains "(proxied)". | | `ssl_ja3` | [[link,ssl_ja3]] composed from TLS Client Hello. | | `ssl_ja3_hash` | MD5 hash from [[link,ssl_ja3]] composed from TLS Client Hello. | +| `ssl_client_cert_fp` | [[setting,ssl_peer_certificate_fingerprint_hash]] of client certificate. | +| `ssl_client_cert_pubkey_fp` | [[setting,ssl_peer_certificate_fingerprint_hash]] of client certificate public key. | | `mail_pid` | PID for process that handles the mail session post-login. | | `original_user` | Same as `user`, except using the original username the client sent before any changes by auth process. With master user logins (also with [[setting,auth_master_user_separator]] based logins),this contains only the original master username. | | `listener` | Socket listener name as specified in config file, which accepted the client connection. | @@ -322,6 +324,8 @@ See also: | `password` | Cleartext password from cleartext authentication mechanism. | | `secured` | "TLS" with established SSL/TLS connections, "secured" with secured connections (see: [[setting,ssl]]). Otherwise empty. | | `ssl_ja3_hash` | MD5 hash from JA3 string composed from TLS Client Hello. | +| `ssl_client_cert_fp` | [[setting,ssl_peer_certificate_fingerprint_hash]] of client certificate. | +| `ssl_client_cert_pubkey_fp` | [[setting,ssl_peer_certificate_fingerprint_hash]] of client certificate public key. | | `cert` | "valid" if client had sent a valid client certificate, otherwise empty. | | `login_user` | For master user logins: Logged in user@domain. | | `master_user` | For master user logins: The master username. |