diff options
Diffstat (limited to 'lib/ssl/doc/src')
| -rw-r--r-- | lib/ssl/doc/src/notes.xml | 104 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl.xml | 125 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_app.xml | 4 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_crl_cache_api.xml | 15 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_distribution.xml | 1 |
5 files changed, 137 insertions, 112 deletions
diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml index 5fb76c1f62..c427db24a4 100644 --- a/lib/ssl/doc/src/notes.xml +++ b/lib/ssl/doc/src/notes.xml @@ -28,109 +28,45 @@ <p>This document describes the changes made to the SSL application.</p> -<section><title>SSL 8.0</title> +<section><title>SSL 7.3.3</title> <section><title>Fixed Bugs and Malfunctions</title> <list> <item> <p> - Timeouts may have the value 0, gauards have been - corrected to allow this</p> - <p> - Own Id: OTP-13635</p> - </item> - </list> - </section> - - - <section><title>Improvements and New Features</title> - <list> - <item> - <p> - Remove default support for DES cipher suites</p> - <p> - *** POTENTIAL INCOMPATIBILITY ***</p> - <p> - Own Id: OTP-13195</p> - </item> - <item> - <p> - Deprecate the function crypto:rand_bytes and make sure - that crypto:strong_rand_bytes is used in all places that - are cryptographically significant.</p> - <p> - Own Id: OTP-13214</p> - </item> - <item> - <p> - Better error handling of user error during TLS upgrade. - ERL-69 is solved by gen_statem rewrite of ssl - application.</p> - <p> - Own Id: OTP-13255</p> - </item> - <item> - <p> - Provide user friendly error message when crypto rejects a - key</p> - <p> - Own Id: OTP-13256</p> - </item> - <item> - <p> - TLS distribution connections now allow specifying the - options <c>verify_fun</c>, <c>crl_check</c> and - <c>crl_cache</c>. See the documentation. GitHub pull req - #956 contributed by Magnus Henoch.</p> - <p> - Own Id: OTP-13429 Aux Id: Pull#956 </p> - </item> - <item> - <p> - Remove confusing error message when closing a distributed - erlang node running over TLS</p> - <p> - Own Id: OTP-13431</p> - </item> - <item> - <p> - ssl now uses gen_statem instead of gen_fsm to implement - the ssl connection process, this solves some timing - issues in addtion to making the code more intuitive as - the behaviour can be used cleanly instead of having a lot - of workaround for shortcomings of the behaviour.</p> - <p> - Own Id: OTP-13464</p> - </item> - <item> - <p> - Correct ssl:prf/5 to use the negotiated cipher suites prf - function in ssl:prf/5 instead of the default prf.</p> + Correct ssl:prf/5 to use the negotiated cipher suite's + prf function in ssl:prf/5 instead of the default prf.</p> <p> Own Id: OTP-13546</p> </item> <item> <p> - Some legacy TLS 1.0 software does not tolerate the 1/n-1 - content split BEAST mitigation technique. Add a - beast_mitigation SSL option (defaulting to - one_n_minus_one) to select or disable the BEAST - mitigation technique.</p> + Timeouts may have the value 0, guards have been corrected + to allow this</p> <p> - Own Id: OTP-13629</p> + Own Id: OTP-13635</p> </item> <item> <p> - Enhance error log messages to facilitate for users to - understand the error</p> + Change of internal handling of hash sign pairs as the + used one enforced to much restrictions making some valid + combinations unavailable.</p> <p> - Own Id: OTP-13632</p> + Own Id: OTP-13670</p> </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> <item> <p> - Incresed default DH params to 2048-bit</p> + Create a little randomness in sending of session + invalidation messages, to mitigate load when whole table + is invalidated.</p> <p> - Own Id: OTP-13636</p> + Own Id: OTP-13490</p> </item> </list> </section> diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 33ece8f769..abba5aaf59 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} | @@ -415,25 +464,28 @@ fun(srp, Username :: string(), UserState :: term()) -> <tag><c>{padding_check, boolean()}</c></tag> <item><p>Affects TLS-1.0 connections only. If set to <c>false</c>, it disables the block cipher padding check - to be able to interoperate with legacy software.</p></item> - - <warning><p>Using <c>{padding_check, boolean()}</c> makes TLS + to be able to interoperate with legacy software.</p> + <warning><p>Using <c>{padding_check, boolean()}</c> makes TLS vulnerable to the Poodle attack.</p></warning> + </item> + + <tag><c>{beast_mitigation, one_n_minus_one | zero_n | disabled}</c></tag> <item><p>Affects SSL-3.0 and TLS-1.0 connections only. Used to change the BEAST mitigation strategy to interoperate with legacy software. - Defaults to <c>one_n_minus_one</c></p>. + Defaults to <c>one_n_minus_one</c>.</p> <p><c>one_n_minus_one</c> - Perform 1/n-1 BEAST mitigation.</p> <p><c>zero_n</c> - Perform 0/n BEAST mitigation.</p> - <p><c>disabled</c> - Disable BEAST mitigation.</p></item> + <p><c>disabled</c> - Disable BEAST mitigation.</p> - <warning><p>Using <c>{beast_mitigation, disabled}</c> makes SSL or TLS + <warning><p>Using <c>{beast_mitigation, disabled}</c> makes SSL or TLS vulnerable to the BEAST attack.</p></warning> - </taglist> + </item> + </taglist> </section> @@ -546,7 +598,7 @@ fun(srp, Username :: string(), UserState :: term()) -> TLS handshake. If no lower TLS versions than 1.2 are supported, the client will send a TLS signature algorithm extension with the algorithms specified by this option. - Defaults to + Defaults to</p> <code>[ %% SHA2 @@ -563,7 +615,7 @@ fun(srp, Username :: string(), UserState :: term()) -> {sha, rsa}, {sha, dsa}, ]</code> - +<p> The algorithms should be in the preferred order. Selected signature algorithm can restrict which hash functions that may be selected. Default support for {md5, rsa} removed in ssl-8.0 @@ -706,6 +758,12 @@ fun(srp, Username :: string(), UserState :: term()) -> client certificate is requested. For more details see the <seealso marker="#client_signature_algs">corresponding client option</seealso>. </p> </item> + <tag><c>{v2_hello_compatible, boolean()}</c></tag> + <item>If true, the server accepts clients that send hello messages on SSL-2.0 format but offers + supported SSL/TLS versions. Defaults to false, that is the server will not interoperate with clients that + offers SSL-2.0. + </item> + </taglist> </section> @@ -895,6 +953,23 @@ fun(srp, Username :: string(), UserState :: term()) -> </func> <func> + <name>getstat(Socket) -> + {ok, OptionValues} | {error, inet:posix()}</name> + <name>getstat(Socket, OptionNames) -> + {ok, OptionValues} | {error, inet:posix()}</name> + <fsummary>Get one or more statistic options for a socket</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>OptionNames = [atom()]</v> + <v>OptionValues = [{inet:stat_option(), integer()}]</v> + </type> + <desc> + <p>Gets one or more statistic options for the underlying TCP socket.</p> + <p>See inet:getstat/2 for statistic options description.</p> + </desc> + </func> + + <func> <name>listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}</name> <fsummary>Creates an SSL listen socket.</fsummary> diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml index e50ffdbfe6..0b3fa9a8a9 100644 --- a/lib/ssl/doc/src/ssl_app.xml +++ b/lib/ssl/doc/src/ssl_app.xml @@ -109,7 +109,7 @@ <item><p>List of extra user-defined arguments to the <c>init</c> function in the session cache callback module. Defaults to <c>[]</c>.</p></item> - <tag><c><![CDATA[session_cache_client_max = integer() <optional>]]></c><br/> + <tag><c><![CDATA[session_cache_client_max = integer() <optional>]]></c><br/></tag> <item><p>Limits the growth of the clients session cache, that is how many sessions towards servers that are cached to be used by new client connections. If the maximum number of sessions is @@ -142,8 +142,6 @@ shutdown gracefully. Defaults to 5000 milliseconds. </p> </item> - </tag> - </taglist> </section> 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> diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml index 495e02d271..4bd5f67202 100644 --- a/lib/ssl/doc/src/ssl_distribution.xml +++ b/lib/ssl/doc/src/ssl_distribution.xml @@ -98,6 +98,7 @@ {stdlib,"1.18"}, {crypto, "2.0.3"}, {public_key, "0.12"}, + {asn1, "4.0"}, {ssl, "5.0"} ]}. </code> |