Document peer certificate fingerprinting

Author: cmouse

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]]' ],

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_<anything>`
 
 In a proxy, pass the variable to the next hop (backend) as

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