Document peer certificate fingerprinting #1170
Conversation
| 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\` |
There was a problem hiding this comment.
enables [[link,passdb_check_client_fp,ssl_client_cert_fp and ssl_client_cert_pubkey_fp]]
There was a problem hiding this comment.
um, no, those are variables, not extra fields
There was a problem hiding this comment.
Should say %{ssl_client_cert_fp} and %{ssl_client_cert_pubkey_fp} variables then
Also, I thought this setting was required for check_client_fp to work? That should be mentioned/linked in another sentence then.
|
|
||
| ##### `check_client_cert_fp` | ||
|
|
||
| Match client certificate fingerprint. See [[setting,ssl_peer_certificate_fingerprint_hash]]. |
There was a problem hiding this comment.
How about:
- Match client certificate (but not public key) fingerprint.
See [[link,passdb_check_client_fp]]
There was a problem hiding this comment.
I think client certificate contains public key always, so it is implicitly checked.
There was a problem hiding this comment.
I intended to differentiate the different check_client_*_fp fields with that comment. If it public key fingerprint is somehow implicitly checked, how are check_client_cert_fp and check_client_fp any different?
|
|
||
| This is intended to be used instead of verifying certificates with CA certificates. 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. |
There was a problem hiding this comment.
That's a bit strange text. "With CA authentication can only fail, but with fingerprints authentication is failed." so kind of the same. Also now it sounds like this is the main reason for using fingerprints. Should it be rather something like:
This can be used for verifying client certificates using per-user fingerprints stored in a database rather than relying on CA certificates.
If the fingerprints don't match, it's treated as a passdb failure ([[setting,passdb_result_failure]]). This allows the next passdb to continue authenticating the user in a different way. If CA certificates are used, the authentication can only fail without a fallback.
Although now I'm a bit confused about your sentence above "you can only fail authentication if the value is non-empty and does not match". Do you mean if CA certificates are used together with check_client_fp? Is there some point in doing that? Or what is this "value is non-empty" you refer to?
There was a problem hiding this comment.
i clarified the text a bit. the only point is to do public key pinning, so you can be sure that the client is not using a cert with similar username but issued by some other CA or reissued to different public key.
docs/core/config/auth/passdb.md
Outdated
| ::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. | ||
|
|
||
| This also requires [[setting,auth_ssl_require_client_cert,yes]] to work. |
There was a problem hiding this comment.
That doesn't seem to be true. As long as a certificate is provided, passdb passes even with auth_ssl_require_client_cert=no. Should we change it in the code that it really is required to prevent misconfigurations?
There was a problem hiding this comment.
if auth_ssl_require_client_cert, then nothing enforces that the cert is valid.
docs/core/config/auth/passdb.md
Outdated
| 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. | ||
|
|
||
| See [[setting,ssl_server_request_client_cert]] on how to allow any certificate. |
There was a problem hiding this comment.
Maybe we need a clear bulletin point list what is required for this to work as expected:
- [[setting,auth_ssl_require_client_cert,yes]]
- [[setting,ssl_server_request_client_cert,any-cert]] to skip CA certificate checks
- passdb
check_client_fp,check_client_cert_fporcheck_client_publkey_fpwhere the value contains the user's client certificate's fingerprint
JIRA: DOV-7328