diff options
Diffstat (limited to 'lib/ssl/doc')
| -rw-r--r-- | lib/ssl/doc/src/notes.xml | 342 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl.xml | 81 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_app.xml | 10 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_crl_cache_api.xml | 2 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_distribution.xml | 6 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_session_cache_api.xml | 31 |
6 files changed, 445 insertions, 27 deletions
diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml index 3b6f988a2d..5a39cac9bc 100644 --- a/lib/ssl/doc/src/notes.xml +++ b/lib/ssl/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1999</year><year>2016</year> + <year>1999</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,6 +28,346 @@ <p>This document describes the changes made to the SSL application.</p> +<section><title>SSL 8.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + ECDH-ECDSA key exchange supported, was accidently + dismissed in earlier versions.</p> + <p> + Own Id: OTP-14421</p> + </item> + <item> + <p> + Correct close semantics for active once connections. This + was a timing dependent bug the resulted in the close + message not always reaching the ssl user process.</p> + <p> + Own Id: OTP-14443</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + TLS-1.2 clients will now always send hello messages on + its own format, as opposed to earlier versions that will + send the hello on the lowest supported version, this is a + change supported by the latest RFC.</p> + <p> + This will make interoperability with some newer servers + smoother. Potentially, but unlikely, this could cause a + problem with older servers if they do not adhere to the + RFC and ignore unknown extensions.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13820</p> + </item> + <item> + <p> + Allow Erlang/OTP to use OpenSSL in FIPS-140 mode, in + order to satisfy specific security requirements (mostly + by different parts of the US federal government). </p> + <p> + See the new crypto users guide "FIPS mode" chapter about + building and using the FIPS support which is disabled by + default.</p> + <p> + (Thanks to dszoboszlay and legoscia)</p> + <p> + Own Id: OTP-13921 Aux Id: PR-1180 </p> + </item> + <item> + <p> + Implemented DTLS cookie generation, required by spec, + instead of using a hardcoded value.</p> + <p> + Own Id: OTP-14076</p> + </item> + <item> + <p> + Implement sliding window replay protection of DTLS + records.</p> + <p> + Own Id: OTP-14077</p> + </item> + <item> + <p> + TLS client processes will by default call + public_key:pkix_verify_hostname/2 to verify the hostname + of the connection with the server certificates specified + hostname during certificate path validation. The user may + explicitly disables it. Also if the hostname can not be + derived from the first argument to connect or is not + supplied by the server name indication option, the check + will not be performed.</p> + <p> + Own Id: OTP-14197</p> + </item> + <item> + <p> + Extend connection_information/[1,2] . The values + session_id, master_secret, client_random and + server_random can no be accessed by + connection_information/2. Note only session_id will be + added to connection_information/1. The rational is that + values concerning the connection security should have to + be explicitly requested.</p> + <p> + Own Id: OTP-14291</p> + </item> + <item> + <p> + Chacha cipher suites are currently not tested enough to + be most preferred ones</p> + <p> + Own Id: OTP-14382</p> + </item> + <item> + <p> + Basic support for DTLS that been tested together with + OpenSSL.</p> + <p> + Test by providing the option {protocol, dtls} to the ssl + API functions connect and listen.</p> + <p> + Own Id: OTP-14388</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 8.1.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Remove debug printout</p> + <p> + Own Id: OTP-14396</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 8.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Correct active once emulation, for TLS. Now all data + received by the connection process will be delivered + through active once, even when the active once arrives + after that the gen_tcp socket is closed by the peer.</p> + <p> + Own Id: OTP-14300</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 8.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Corrected termination behavior, that caused a PEM cache + bug and sometimes resulted in connection failures.</p> + <p> + Own Id: OTP-14100</p> + </item> + <item> + <p> + Fix bug that could hang ssl connection processes when + failing to require more data for very large handshake + packages. Add option max_handshake_size to mitigate DoS + attacks.</p> + <p> + Own Id: OTP-14138</p> + </item> + <item> + <p> + Improved support for CRL handling that could fail to work + as intended when an id-ce-extKeyUsage was present in the + certificate. Also improvements where needed to + distributionpoint handling so that all revocations + actually are found and not deemed to be not determinable.</p> + <p> + Own Id: OTP-14141</p> + </item> + <item> + <p> + A TLS handshake might accidentally match old sslv2 format + and ssl application would incorrectly aborted TLS + handshake with ssl_v2_client_hello_no_supported. Parsing + was altered to avoid this problem.</p> + <p> + Own Id: OTP-14222</p> + </item> + <item> + <p> + Correct default cipher list to prefer AES 128 before 3DES</p> + <p> + Own Id: OTP-14235</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Move PEM cache to a dedicated process, to avoid making + the SSL manager process a bottleneck. This improves + scalability of TLS connections.</p> + <p> + Own Id: OTP-13874</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 8.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + List of possible anonymous suites, never supported by + default, where incorrect for some TLS versions.</p> + <p> + Own Id: OTP-13926</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Experimental version of DTLS. It is runnable but not + complete and cannot be considered reliable for production + usage.</p> + <p> + Own Id: OTP-12982</p> + </item> + <item> + <p> + Add API options to handle ECC curve selection.</p> + <p> + Own Id: OTP-13959</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 8.0.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A timing related bug in event handling could cause + interoperability problems between an erlang TLS server + and some TLS clients, especially noticed with Firefox as + TLS client.</p> + <p> + Own Id: OTP-13917</p> + </item> + <item> + <p> + Correct ECC curve selection, the error could cause the + default to always be selected.</p> + <p> + Own Id: OTP-13918</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 8.0.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Correctly formed handshake messages received out of order + will now correctly fail the connection with unexpected + message.</p> + <p> + Own Id: OTP-13853</p> + </item> + + <item> + <p>Correct handling of signature algorithm selection</p> + <p> + Own Id: OTP-13711</p> + </item> + + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + ssl application now behaves gracefully also on partially + incorrect input from peer.</p> + <p> + Own Id: OTP-13834</p> + </item> + <item> + <p> + Add application environment configuration + bypass_pem_cache. This can be used as a workaround for + the current implementation of the PEM-cache that has + proven to be a bottleneck.</p> + <p> + Own Id: OTP-13883</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 8.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The TLS/SSL protocol version selection for the SSL server + has been corrected to follow RFC 5246 Appendix E.1 + especially in case where the list of supported versions + has gaps. Now the server selects the highest protocol + version it supports that is not higher than what the + client supports.</p> + <p> + Own Id: OTP-13753 Aux Id: seq13150 </p> + </item> + </list> + </section> + +</section> + <section><title>SSL 8.0</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index abba5aaf59..ca2dcbb761 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1999</year><year>2016</year> + <year>1999</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -127,7 +127,7 @@ <item><p><c>hostname() | ipaddress()</c></p></item> <tag><c>hostname() =</c></tag> - <item><p><c>string()</c></p></item> + <item><p><c>string() - DNS hostname</c></p></item> <tag><c>ip_address() =</c></tag> <item><p><c>{N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6 @@ -155,7 +155,7 @@ <tag><c>cipher() =</c></tag> <item><p><c>rc4_128 | des_cbc | '3des_ede_cbc' - | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm</c></p></item> + | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm | chacha20_poly1305</c></p></item> <tag><c>hash() =</c></tag> <item><p><c>md5 | sha | sha224 | sha256 | sha348 | sha512</c></p></item> @@ -170,6 +170,14 @@ <tag><c>SNIfun::fun()</c></tag> <item><p><c>= fun(ServerName :: string()) -> [ssl_option()]</c></p></item> + <tag><c>named_curve() =</c></tag> + <item><p><c>sect571r1 | sect571k1 | secp521r1 | brainpoolP512r1 + | sect409k1 | sect409r1 | brainpoolP384r1 | secp384r1 + | sect283k1 | sect283r1 | brainpoolP256r1 | secp256k1 | secp256r1 + | sect239k1 | sect233k1 | sect233r1 | secp224k1 | secp224r1 + | sect193r1 | sect193r2 | secp192k1 | secp192r1 | sect163k1 + | sect163r1 | sect163r2 | secp160k1 | secp160r1 | secp160r2</c></p></item> + </taglist> </section> @@ -181,6 +189,11 @@ <taglist> + <tag><c>{protocol, tls | dtls}</c></tag> + <item><p>Choose TLS or DTLS protocol for the transport layer security. + Defaults to <c>tls</c> Introduced in OTP 20, DTLS support is considered + experimental in this release. DTLS over other transports than UDP are not yet supported.</p></item> + <tag><c>{cert, public_key:der_encoded()}</c></tag> <item><p>The DER-encoded users certificate. If this option is supplied, it overrides option <c>certfile</c>.</p></item> @@ -217,6 +230,11 @@ Anonymous cipher suites are supported for testing purposes only and are not be used when security matters.</p></item> + <tag><c>{eccs, [named_curve()]}</c></tag> + <item><p> Allows to specify the order of preference for named curves + and to restrict their usage when using a cipher suite supporting them. + </p></item> + <tag><c>{secure_renegotiate, boolean()}</c></tag> <item><p>Specifies if to reject renegotiation attempt that does not live up to @@ -236,7 +254,7 @@ be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 1.</p></item> - <tag><c>{verify_fun, {Verifyfun :: fun(), InitialUserState :: + <tag><marker id="verify_fun"/><c>{verify_fun, {Verifyfun :: fun(), InitialUserState :: term()}}</c></tag> <item><p>The verification fun is to be defined as follows:</p> @@ -411,6 +429,14 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid </taglist> </item> + + <tag><c>max_handshake_size</c></tag> + <item> + <p>Integer (24 bits unsigned). Used to limit the size of + valid TLS handshake packets to avoid DoS attacks. + Defaults to 256*1024.</p> + </item> + </taglist> </item> @@ -561,15 +587,23 @@ fun(srp, Username :: string(), UserState :: term()) -> <item><p>Specifies the username and password to use to authenticate to the server.</p></item> - <tag><c>{server_name_indication, hostname()}</c></tag> - <item><p>Can be specified when upgrading a TCP socket to a TLS - socket to use the TLS Server Name Indication extension.</p></item> + <tag><c>{server_name_indication, HostName :: hostname()}</c></tag> + <item><p>Specify the hostname to be used in TLS Server Name Indication extension. + Is usefull when upgrading a TCP socket to a TLS socket or if the hostname can not be + derived from the Host argument to <seealso marker="ssl#connect-3">ssl:connect/3</seealso>. + Will also cause the client to preform host name verification of the peer certificate + <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname(PeerCert, [{dns_id, HostName}])</seealso> + </p> during the x509-path validation. If the check fails the error {bad_cert, hostname_check_failiure} will be + propagated to the path validation fun <seealso marker="#verify_fun">verify_fun</seealso> + </item> <tag><c>{server_name_indication, disable}</c></tag> <item> <p>When starting a TLS connection without upgrade, the Server Name - Indication extension is sent if possible. This option can be - used to disable that behavior.</p> + Indication extension is sent if possible that is can be derived from the Host argument + to <seealso marker="ssl#connect-3">ssl:connect/3</seealso>. + This option can be used to disable that behavior.</p> + <note><p> Note that this also disables the default host name verification check of the peer certificate.</p></note> </item> <tag><c>{fallback, boolean()}</c></tag> <item> @@ -751,6 +785,11 @@ fun(srp, Username :: string(), UserState :: term()) -> (the default), use the client's preference. </item> + <tag><c>{honor_ecc_order, boolean()}</c></tag> + <item>If true, use the server's preference for ECC curve selection. If false + (the default), use the client's preference. + </item> + <tag><c>{signature_algs, [{hash(), ecdsa | rsa | dsa}]}</c></tag> <item><p> The algorithms specified by this option will be the ones accepted by the server in a signature algorithm @@ -804,6 +843,17 @@ fun(srp, Username :: string(), UserState :: term()) -> </func> <func> + <name>eccs() -></name> + <name>eccs(protocol()) -> [named_curve()]</name> + <fsummary>Returns a list of supported ECCs.</fsummary> + + <desc><p>Returns a list of supported ECCs. <c>eccs()</c> + is equivalent to calling <c>eccs(Protocol)</c> with all + supported protocols and then deduplicating the output.</p> + </desc> + </func> + + <func> <name>clear_pem_cache() -> ok </name> <fsummary> Clears the pem cache</fsummary> @@ -898,13 +948,14 @@ fun(srp, Username :: string(), UserState :: term()) -> <fsummary>Returns all the connection information. </fsummary> <type> - <v>Item = protocol | cipher_suite | sni_hostname | atom()</v> + <v>Item = protocol | cipher_suite | sni_hostname | ecc | session_id | atom()</v> <d>Meaningful atoms, not specified above, are the ssl option names.</d> <v>Result = [{Item::atom(), Value::term()}]</v> <v>Reason = term()</v> </type> - <desc><p>Returns all relevant information about the connection, ssl options that - are undefined will be filtered out.</p> + <desc><p>Returns the most relevant information about the connection, ssl options that + are undefined will be filtered out. Note that values that affect the security of the + connection will only be returned if explicitly requested by connection_information/2.</p> </desc> </func> @@ -915,8 +966,10 @@ fun(srp, Username :: string(), UserState :: term()) -> </fsummary> <type> <v>Items = [Item]</v> - <v>Item = protocol | cipher_suite | sni_hostname | atom()</v> - <d>Meaningful atoms, not specified above, are the ssl option names.</d> + <v>Item = protocol | cipher_suite | sni_hostname | ecc | session_id | client_random + | server_random | master_secret | atom()</v> + <d>Note that client_random, server_random and master_secret are values + that affect the security of connection. Meaningful atoms, not specified above, are the ssl option names.</d> <v>Result = [{Item::atom(), Value::term()}]</v> <v>Reason = term()</v> </type> diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml index a66e947bc1..f317dfded4 100644 --- a/lib/ssl/doc/src/ssl_app.xml +++ b/lib/ssl/doc/src/ssl_app.xml @@ -141,6 +141,16 @@ marker="ssl#clear_pem_cache-0">ssl:clear_pem_cache/0</seealso> </item> + + <tag><c><![CDATA[bypass_pem_cache = boolean() <optional>]]></c></tag> + <item> + <p>Introduced in ssl-8.0.2. Disables the PEM-cache. + The PEM cache has proven to be a bottleneck, until the + implementation has been improved this can be used as + a workaround. Defaults to false. + </p> + </item> + <tag><c><![CDATA[alert_timeout = integer() <optional>]]></c></tag> <item> <p> diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml index 7440b6ef04..c6774b4df6 100644 --- a/lib/ssl/doc/src/ssl_crl_cache_api.xml +++ b/lib/ssl/doc/src/ssl_crl_cache_api.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2015</year><year>2015</year> + <year>2015</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml index 4bd5f67202..61f88e3860 100644 --- a/lib/ssl/doc/src/ssl_distribution.xml +++ b/lib/ssl/doc/src/ssl_distribution.xml @@ -43,7 +43,7 @@ Erlang node distributed, <c>net_kernel</c> uses this module to set up listen ports and connections.</p> - <p>In the SSL application, an exra distribution + <p>In the SSL application, an extra distribution module, <c>inet_tls_dist</c>, can be used as an alternative. All distribution connections will use SSL and all participating Erlang nodes in a distributed system must use @@ -71,8 +71,8 @@ <section> <title>Building Boot Scripts Including the ssl Application</title> <p>Boot scripts are built using the <c>systools</c> utility in the - <c>sasl</c> application. For more information on <c>systools</c>, - see the <c>sasl</c> documentation. This is only an example of + SASL application. For more information on <c>systools</c>, + see the SASL documentation. This is only an example of what can be done.</p> <p>The simplest boot script possible includes only the Kernel diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml index b85d8fb284..a84a3dfce9 100644 --- a/lib/ssl/doc/src/ssl_session_cache_api.xml +++ b/lib/ssl/doc/src/ssl_session_cache_api.xml @@ -4,14 +4,14 @@ <erlref> <header> <copyright> - <year>1999</year><year>2015</year> + <year>1999</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -62,8 +62,8 @@ </taglist> </section> - - <funcs> + + <funcs> <func> <name>delete(Cache, Key) -> _</name> @@ -134,7 +134,7 @@ </p> </desc> </func> - + <func> <name>select_session(Cache, PartialKey) -> [session()]</name> <fsummary>Selects sessions that can be reused.</fsummary> @@ -151,6 +151,21 @@ </func> <func> + <name>size(Cache) -> integer()</name> + <fsummary>Returns the number of sessions in the cache.</fsummary> + <type> + <v>Cache = cache_ref()</v> + </type> + <desc> + <p>Returns the number of sessions in the cache. If size + exceeds the maximum number of sessions, the current cache + entries will be invalidated regardless of their remaining + lifetime. Is to be callable from any process. + </p> + </desc> + </func> + + <func> <name>terminate(Cache) -> _</name> <fsummary>Called by the process that handles the cache when it is about to terminate.</fsummary> @@ -178,7 +193,7 @@ </p> </desc> </func> - - </funcs> - + + </funcs> + </erlref> |