From b8e9348702ffcaf9f2099e1e609ad1bf53007074 Mon Sep 17 00:00:00 2001
From: Tangui Le Pense <29804907+tanguilp@users.noreply.github.com>
Date: Tue, 6 Feb 2024 23:12:53 +0300
Subject: [PATCH] Update doc wr to crl_check and use of best_effort instead of
 true

---
 docs/secure_coding_and_deployment_hardening/ssl.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/secure_coding_and_deployment_hardening/ssl.md b/docs/secure_coding_and_deployment_hardening/ssl.md
index 8bda581..c6f2963 100644
--- a/docs/secure_coding_and_deployment_hardening/ssl.md
+++ b/docs/secure_coding_and_deployment_hardening/ssl.md
@@ -60,7 +60,7 @@ Make sure to test the selected options against test endpoints, such as those pro
 
 ## Revocation check
 
-One scenario that’s not handled by the above examples is certificate revocation: no revocation check is performed, and therefore a revoked but otherwise valid certificate would be accepted. It is possible to check certificates against the CA’s Certificate Revocation List (CRL) by setting the `crl_check` option to true. This also requires the `crl_cache` to be configured:
+One scenario that’s not handled by the above examples is certificate revocation: no revocation check is performed, and therefore a revoked but otherwise valid certificate would be accepted. It is possible to check certificates against the CA’s Certificate Revocation List (CRL) by setting the `crl_check` option to `best_effort`. This also requires the `crl_cache` to be configured:
 
 ```erlang
 %% Erlang
@@ -71,7 +71,7 @@ ssl:connect("revoked.badssl.com", 443, [
     {customize_hostname_check, [
         {match_fun, public_key:pkix_verify_hostname_match_fun(https)}
     ]},
-    {crl_check, true},
+    {crl_check, best_effort},
     {crl_cache, {ssl_crl_cache, {internal, [{http, 1000}]}}}
 ]).
 ```
@@ -85,11 +85,13 @@ ssl:connect("revoked.badssl.com", 443, [
   customize_hostname_check: [
     match_fun: :public_key.pkix_verify_hostname_match_fun(:https)
   ],
-  crl_check: true,
+  crl_check: :best_effort,
   crl_cache: {:ssl_crl_cache, {:internal, [http: 1000]}}
 )
 ```
 
+The stricter `true` can be used instead of `best_effort`: in this case validation will fail if CRL is missing, which can happen if the certificate has no CRL or exclusively uses OCSP.
+
 However, please note that the `ssl_crl_cache` module does not actually cache the CRL contents, so each handshake will trigger a new CRL lookup, which impacts the performance and reliability of TLS connections. In applications that require revocation checks as well as high throughput a custom CRL cache implementation will be needed.
 
 ## Selecting protocol versions and ciphers