Document peer certificate fingerprinting

Author: cmouse

data/settings.js

@@ -10272,6 +10272,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]]' ],
+		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

@@ -442,6 +442,23 @@ 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. See [[setting,ssl_peer_certificate_fingerprint_hash]].
+If there is no match, authentication fails.
+
+##### `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.
+
+##### `check_client_pubkey_fp`
+
+Match client public key fingerprint. See [[setting,ssl_peer_certificate_fingerprint_hash]].
+
+Public key fingerprint is calculated by taking hash value of DER encoded certificate public key.
+
 #### `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. |