Document peer certificate fingerprinting

Author: cmouse

data/settings.js

@@ -10290,6 +10290,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 is required for \`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 disallowed, 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,42 @@ 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.
+
+This is intended to replace CA certificates with verifying client certificates using fingerprints, or to enforce
+that particular public key or certificate is being used.
+
+To enable this feature, you need to configure:
+
+ * [[setting,auth_ssl_require_client_cert,yes]]
+ * [[setting,ssl_peer_certificate_fingerprint_hash,sha256]], or some other valid hash
+ * [[setting,ssl_server_request_client_cert,any-cert]] if you don't want to validate cert against certificate authority
+
+::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.
+
+When feature is enabled, and certificate has not been validated by certificate authority (or is self-signed), at least one passdb must successfully match the fingerprint, otherwise the whole authentication will fail with "Client didn't present valid SSL certificate".
+
+If your certificate is authenticated by certificate authority, using any of the fingerprint matching keywords will fail that passdb if the fingerprint does not match, but next password database can still authenticate the user. Note though that none of the passdbs are required to successfully match the fingerprint in this case.
+
+##### `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. |