Merge branch 'legoscia/ssl_crl_hash_dir-bis/PR-982/OTP-13530'

* legoscia/ssl_crl_hash_dir-bis/PR-982/OTP-13530:
  Skip crl_hash_dir_expired test for LibreSSL
  Add ssl_crl_hash_dir module
  Function for generating OpenSSL-style name hashes
  Add public_key:pkix_match_dist_point
  Improve formatting for crl_{check,cache} options
  Add issuer arg to ssl_crl_cache_api lookup callback

Conflicts:
	lib/public_key/test/public_key_SUITE.erl

2 files changed, 80 insertions, 16 deletions

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index bed82cdb91..4ea000802f 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -331,39 +331,88 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
 
       <tag><c>{crl_check, boolean() | peer | best_effort }</c></tag>
       <item>
-	Perform CRL (Certificate Revocation List) verification
+	<p>Perform CRL (Certificate Revocation List) verification
 	<seealso marker="public_key:public_key#pkix_crls_validate-3">
 	(public_key:pkix_crls_validate/3)</seealso> on all the certificates during the path validation
 	<seealso
 	    marker="public_key:public_key#pkix_path_validation-3">(public_key:pkix_path_validation/3)
 	</seealso>
-	of the certificate chain. Defaults to false.
+	of the certificate chain. Defaults to <c>false</c>.</p>
 	
-	<p><c>peer</c> - check is only performed on
-	the peer certificate.</p>
+	<taglist>
+	  <tag><c>peer</c></tag>
+	  <item>check is only performed on the peer certificate.</item>
 
-	<p><c>best_effort</c> - if certificate revocation status can not be determined
-	it will be accepted as valid.</p>
+	  <tag><c>best_effort</c></tag>
+	  <item>if certificate revocation status can not be determined
+	  it will be accepted as valid.</item>
+	</taglist>
 
 	<p>The CA certificates specified for the connection will be used to 
 	construct the certificate chain validating the CRLs.</p>
  	
-	<p>The CRLs will be fetched from a local or external cache see
+	<p>The CRLs will be fetched from a local or external cache. See
 	<seealso marker="ssl:ssl_crl_cache_api">ssl_crl_cache_api(3)</seealso>.</p>
       </item>
 
       <tag><c>{crl_cache, {Module :: atom(), {DbHandle :: internal | term(), Args :: list()}}}</c></tag>
       <item>
-	<p>Module defaults to ssl_crl_cache with <c> DbHandle </c> internal and an
-	empty argument list. The following arguments may be specified for the internal cache.</p>
+	<p>Specify how to perform lookup and caching of certificate revocation lists.
+	<c>Module</c> defaults to <seealso marker="ssl:ssl_crl_cache">ssl_crl_cache</seealso>
+	with <c> DbHandle </c> being <c>internal</c> and an
+	empty argument list.</p>
+
+	<p>There are two implementations available:</p>
+
 	<taglist>
-	  <tag><c>{http, timeout()}</c></tag>
-	  <item><p>
-	    Enables fetching of CRLs specified as http URIs in<seealso 
-	    marker="public_key:public_key_records"> X509 certificate extensions.</seealso>
-	    Requires the OTP inets application.</p>
-	  </item>	    
-	</taglist>    
+	  <tag><c>ssl_crl_cache</c></tag>
+	  <item>
+	    <p>This module maintains a cache of CRLs.  CRLs can be
+	    added to the cache using the function <seealso
+	    marker="ssl:ssl_crl_cache#insert-1">ssl_crl_cache:insert/1</seealso>,
+	    and optionally automatically fetched through HTTP if the
+	    following argument is specified:</p>
+
+	    <taglist>
+	      <tag><c>{http, timeout()}</c></tag>
+	      <item><p>
+		Enables fetching of CRLs specified as http URIs in<seealso
+		marker="public_key:public_key_records">X509 certificate extensions</seealso>.
+		Requires the OTP inets application.</p>
+	      </item>
+	    </taglist>
+	  </item>
+
+	  <tag><c>ssl_crl_hash_dir</c></tag>
+	  <item>
+	    <p>This module makes use of a directory where CRLs are
+	    stored in files named by the hash of the issuer name.</p>
+
+	    <p>The file names consist of eight hexadecimal digits
+	    followed by <c>.rN</c>, where <c>N</c> is an integer,
+	    e.g. <c>1a2b3c4d.r0</c>.  For the first version of the
+	    CRL, <c>N</c> starts at zero, and for each new version,
+	    <c>N</c> is incremented by one.  The OpenSSL utility
+	    <c>c_rehash</c> creates symlinks according to this
+	    pattern.</p>
+
+	    <p>For a given hash value, this module finds all
+	    consecutive <c>.r*</c> files starting from zero, and those
+	    files taken together make up the revocation list.  CRL
+	    files whose <c>nextUpdate</c> fields are in the past, or
+	    that are issued by a different CA that happens to have the
+	    same name hash, are excluded.</p>
+
+	    <p>The following argument is required:</p>
+
+	    <taglist>
+	      <tag><c>{dir, string()}</c></tag>
+	      <item><p>Specifies the directory in which the CRLs can be found.</p></item>
+	    </taglist>
+
+	  </item>
+	</taglist>
+
       </item>
 
       <tag><c>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} |
diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml
index 03ac010bfe..7440b6ef04 100644
--- a/lib/ssl/doc/src/ssl_crl_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache_api.xml
@@ -76,10 +76,13 @@
     </func>
     
     <func>
+      <name>lookup(DistributionPoint, Issuer, DbHandle) -> not_available | CRLs </name>
       <name>lookup(DistributionPoint, DbHandle) -> not_available | CRLs </name>
       <fsummary> </fsummary>
       <type>
         <v> DistributionPoint = dist_point() </v>
+        <v> Issuer = <seealso
+	marker="public_key:public_key">public_key:issuer_name()</seealso> </v>
 	<v> DbHandle  = cache_ref() </v>
 	<v> CRLs = [<seealso
 	   marker="public_key:public_key">public_key:der_encoded()</seealso>] </v>
@@ -87,6 +90,18 @@
 	<desc> <p>Lookup the CRLs belonging to the distribution point <c> Distributionpoint</c>.
 	This function may choose to only look in the cache or to follow distribution point
 	links depending on how the cache is administrated. </p>
+
+	<p>The <c>Issuer</c> argument contains the issuer name of the
+	certificate to be checked.  Normally the returned CRL should
+	be issued by this issuer, except if the <c>cRLIssuer</c> field
+	of <c>DistributionPoint</c> has a value, in which case that
+	value should be used instead.</p>
+
+	<p>In an earlier version of this API, the <c>lookup</c>
+	function received two arguments, omitting <c>Issuer</c>.  For
+	compatibility, this is still supported: if there is no
+	<c>lookup/3</c> function in the callback module,
+	<c>lookup/2</c> is called instead.</p>
 	</desc>
     </func>