aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc/src
diff options
context:
space:
mode:
authorIngela Anderton Andin <[email protected]>2016-06-14 10:47:38 +0200
committerIngela Anderton Andin <[email protected]>2016-06-14 10:47:38 +0200
commit5268c7b957c30c31e551f197463cdd55a792ea69 (patch)
tree880afe20bbbc06587fe175a8de90a6f4483b0e79 /lib/ssl/doc/src
parent1418cbbb689dc2c88ecceaedb4eba33061d338e7 (diff)
parentc3e06e575b06f25601fdc60f4142a0d6b9e6eb7a (diff)
downloadotp-5268c7b957c30c31e551f197463cdd55a792ea69.tar.gz
otp-5268c7b957c30c31e551f197463cdd55a792ea69.tar.bz2
otp-5268c7b957c30c31e551f197463cdd55a792ea69.zip
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
Diffstat (limited to 'lib/ssl/doc/src')
-rw-r--r--lib/ssl/doc/src/ssl.xml81
-rw-r--r--lib/ssl/doc/src/ssl_crl_cache_api.xml15
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>