diff options
Diffstat (limited to 'lib/ssl/doc/src')
| -rw-r--r-- | lib/ssl/doc/src/book.xml | 2 | ||||
| -rw-r--r-- | lib/ssl/doc/src/notes.xml | 873 | ||||
| -rw-r--r-- | lib/ssl/doc/src/pkix_certs.xml | 2 | ||||
| -rw-r--r-- | lib/ssl/doc/src/release_notes.xml | 2 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl.xml | 394 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_app.xml | 90 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_crl_cache_api.xml | 23 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_distribution.xml | 43 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_session_cache_api.xml | 41 | ||||
| -rw-r--r-- | lib/ssl/doc/src/usersguide.xml | 2 | ||||
| -rw-r--r-- | lib/ssl/doc/src/using_ssl.xml | 2 |
11 files changed, 1314 insertions, 160 deletions
diff --git a/lib/ssl/doc/src/book.xml b/lib/ssl/doc/src/book.xml index a0890a028d..056c958f0f 100644 --- a/lib/ssl/doc/src/book.xml +++ b/lib/ssl/doc/src/book.xml @@ -4,7 +4,7 @@ <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> - <year>1999</year><year>2013</year> + <year>1999</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml index b87b1b4fa7..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>2013</year> + <year>1999</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -26,7 +26,856 @@ <file>notes.xml</file> </header> <p>This document describes the changes made to the SSL application.</p> - <section><title>SSL 7.0</title> + + +<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> + <list> + <item> + <p> + Server now rejects, a not requested client cert, as an + incorrect handshake message and ends the connection.</p> + <p> + Own Id: OTP-13651</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 <c>crypto:rand_bytes</c> and make + sure that <c>crypto:strong_rand_bytes</c> 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> + Add ssl:getstat/1 and ssl:getstat/2</p> + <p> + Own Id: OTP-13415</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> + Remove default support for use of md5 in TLS 1.2 + signature algorithms</p> + <p> + Own Id: OTP-13463</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 addition 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> + Phase out interoperability with clients that offer SSLv2. + By default they are no longer supported, but an option to + provide interoperability is offered.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13465</p> + </item> + <item> + <p> + OpenSSL has functions to generate short (eight hex + digits) hashes of issuers of certificates and CRLs. These + hashes are used by the "c_rehash" script to populate + directories of CA certificates and CRLs, e.g. in the + Apache web server. Add functionality to let an Erlang + program find the right CRL for a given certificate in + such a directory.</p> + <p> + Own Id: OTP-13530</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> + <p> + Own Id: OTP-13629</p> + </item> + <item> + <p> + Enhance error log messages to facilitate for users to + understand the error</p> + <p> + Own Id: OTP-13632</p> + </item> + <item> + <p> + Increased default DH params to 2048-bit</p> + <p> + Own Id: OTP-13636</p> + </item> + <item> + <p> + Propagate CRL unknown CA error so that public_key + validation process continues correctly and determines + what should happen.</p> + <p> + Own Id: OTP-13656</p> + </item> + <item> + <p> + Introduce a flight concept for handshake packages. This + is a preparation for enabling DTLS, however it can also + have a positive effects for TLS on slow and unreliable + networks.</p> + <p> + Own Id: OTP-13678</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 7.3.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <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> + Timeouts may have the value 0, guards have been corrected + to allow this</p> + <p> + Own Id: OTP-13635</p> + </item> + <item> + <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-13670</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Create a little randomness in sending of session + invalidation messages, to mitigate load when whole table + is invalidated.</p> + <p> + Own Id: OTP-13490</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 7.3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Correct cipher suites conversion and gaurd expression. + Caused problems with GCM cipher suites and client side + option to set signature_algorithms extention values.</p> + <p> + Own Id: OTP-13525</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 7.3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Corrections to cipher suite handling using the 3 and 4 + tuple format in addition to commit + 89d7e21cf4ae988c57c8ef047bfe85127875c70c</p> + <p> + Own Id: OTP-13511</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Make values for the TLS-1.2 signature_algorithms + extension configurable</p> + <p> + Own Id: OTP-13261</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 7.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Make sure there is only one poller validator at a time + for validating the session cache.</p> + <p> + Own Id: OTP-13185</p> + </item> + <item> + <p> + A timing related issue could cause ssl to hang, + especially happened with newer versions of OpenSSL in + combination with ECC ciphers.</p> + <p> + Own Id: OTP-13253</p> + </item> + <item> + <p> + Work around a race condition in the TLS distribution + start.</p> + <p> + Own Id: OTP-13268</p> + </item> + <item> + <p> + Big handshake messages are now correctly fragmented in + the TLS record layer.</p> + <p> + Own Id: OTP-13306</p> + </item> + <item> + <p> + Improve portability of ECC tests in Crypto and SSL for + "exotic" OpenSSL versions.</p> + <p> + Own Id: OTP-13311</p> + </item> + <item> + <p> + Certificate extensions marked as critical are ignored + when using verify_none</p> + <p> + Own Id: OTP-13377</p> + </item> + <item> + <p> + If a certificate doesn't contain a CRL Distribution + Points extension, and the relevant CRL is not in the + cache, and the <c>crl_check</c> option is not set to + <c>best_effort</c> , the revocation check should fail.</p> + <p> + Own Id: OTP-13378</p> + </item> + <item> + <p> + Enable TLS distribution over IPv6</p> + <p> + Own Id: OTP-13391</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improve error reporting for TLS distribution</p> + <p> + Own Id: OTP-13219</p> + </item> + <item> + <p> + Include options from connect, listen and accept in + <c>connection_information/1,2</c></p> + <p> + Own Id: OTP-13232</p> + </item> + <item> + <p> + Allow adding extra options for outgoing TLS distribution + connections, as supported for plain TCP connections.</p> + <p> + Own Id: OTP-13285</p> + </item> + <item> + <p> + Use loopback as server option in TLS-distribution module</p> + <p> + Own Id: OTP-13300</p> + </item> + <item> + <p> + Verify certificate signature against original certificate + binary.</p> + <p> + This avoids bugs due to encoding errors when re-encoding + a decode certificate. As there exists several decode step + and using of different ASN.1 specification this is a risk + worth avoiding.</p> + <p> + Own Id: OTP-13334</p> + </item> + <item> + <p> + Use <c>application:ensure_all_started/2</c> instead of + hard-coding dependencies</p> + <p> + Own Id: OTP-13363</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 7.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Honor distribution port range options</p> + <p> + Own Id: OTP-12838</p> + </item> + <item> + <p> + Correct supervisor specification in TLS distribution.</p> + <p> + Own Id: OTP-13134</p> + </item> + <item> + <p> + Correct cache timeout</p> + <p> + Own Id: OTP-13141</p> + </item> + <item> + <p> + Avoid crash and restart of ssl process when key file does + not exist.</p> + <p> + Own Id: OTP-13144</p> + </item> + <item> + <p> + Enable passing of raw socket options on the format + {raw,_,_,_} to the underlying socket.</p> + <p> + Own Id: OTP-13166</p> + </item> + <item> + <p> + Hibernation with small or a zero timeout will now work as + expected</p> + <p> + Own Id: OTP-13189</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add upper limit for session cache, configurable on ssl + application level.</p> + <p> + If upper limit is reached, invalidate the current cache + entries, e.i the session lifetime is the max time a + session will be keept, but it may be invalidated earlier + if the max limit for the table is reached. This will keep + the ssl manager process well behaved, not exhusting + memeory. Invalidating the entries will incrementally + empty the cache to make room for fresh sessions entries.</p> + <p> + Own Id: OTP-12392</p> + </item> + <item> + <p> + Use new time functions to measure passed time.</p> + <p> + Own Id: OTP-12457</p> + </item> + <item> + <p> + Improved error handling in TLS distribution</p> + <p> + Own Id: OTP-13142</p> + </item> + <item> + <p> + Distribution over TLS now honors the nodelay distribution + flag</p> + <p> + Own Id: OTP-13143</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 7.1</title> + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Add DER encoded ECPrivateKey as valid input format for + key option.</p> + <p> + Own Id: OTP-12974</p> + </item> + <item> + <p> + Correct return value of default session callback module</p> + <p> + This error had the symptom that the client check for + unique session would always fail, potentially making the + client session table grow a lot and causing long setup + times.</p> + <p> + Own Id: OTP-12980</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add possibility to downgrade an SSL/TLS connection to a + tcp connection, and give back the socket control to a + user process.</p> + <p> + This also adds the possibility to specify a timeout to + the ssl:close function.</p> + <p> + Own Id: OTP-11397</p> + </item> + <item> + <p> + Add application setting to be able to change fatal alert + shutdown timeout, also shorten the default timeout. The + fatal alert timeout is the number of milliseconds between + sending of a fatal alert and closing the connection. + Waiting a little while improves the peers chances to + properly receiving the alert so it may shutdown + gracefully.</p> + <p> + Own Id: OTP-12832</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 7.0</title> <section><title>Fixed Bugs and Malfunctions</title> <list> @@ -51,12 +900,6 @@ <p> Own Id: OTP-12815</p> </item> - <item> - <p> - Gracefully ignore proprietary hash_sign algorithms</p> - <p> - Own Id: OTP-12829</p> - </item> </list> </section> @@ -107,6 +950,20 @@ </section> +<section><title>SSL 6.0.1.1</title> + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Gracefully ignore proprietary hash_sign algorithms</p> + <p> + Own Id: OTP-12829</p> + </item> + </list> + </section> +</section> + + <section><title>SSL 6.0.1</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/ssl/doc/src/pkix_certs.xml b/lib/ssl/doc/src/pkix_certs.xml index a5793af5ca..f365acef4d 100644 --- a/lib/ssl/doc/src/pkix_certs.xml +++ b/lib/ssl/doc/src/pkix_certs.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/ssl/doc/src/release_notes.xml b/lib/ssl/doc/src/release_notes.xml index 4c9b18f900..2e263c69a7 100644 --- a/lib/ssl/doc/src/release_notes.xml +++ b/lib/ssl/doc/src/release_notes.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1999</year><year>2013</year> + <year>1999</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index f23b71e28b..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>2015</year> + <year>1999</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,37 +31,13 @@ <module>ssl</module> <modulesummary>Interface Functions for Secure Socket Layer</modulesummary> <description> - <p>This module contains interface functions for the SSL.</p> + <p> + This module contains interface functions for the SSL/TLS protocol. + For detailed information about the supported standards see + <seealso marker="ssl_app">ssl(6)</seealso>. + </p> </description> - - <section> - <title>SSL</title> - - <list type="bulleted"> - <item>For application dependencies see <seealso marker="ssl_app"> ssl(6)</seealso> </item> - <item>Supported SSL/TLS-versions are SSL-3.0, TLS-1.0, - TLS-1.1, and TLS-1.2.</item> - <item>For security reasons SSL-2.0 is not supported.</item> - <item>For security reasons SSL-3.0 is no longer supported by default, - but can be configured.</item> - <item>Ephemeral Diffie-Hellman cipher suites are supported, - but not Diffie Hellman Certificates cipher suites.</item> - <item>Elliptic Curve cipher suites are supported if the Crypto - application supports it and named curves are used. - </item> - <item>Export cipher suites are not supported as the - U.S. lifted its export restrictions in early 2000.</item> - <item>IDEA cipher suites are not supported as they have - become deprecated by the latest TLS specification so it is not - motivated to implement them.</item> - <item>CRL validation is supported.</item> - <item>Policy certificate extensions are not supported.</item> - <item>'Server Name Indication' extension client side - (RFC 6066, Section 3) is supported.</item> - </list> - - </section> - + <section> <title>DATA TYPES</title> <p>The following data types are used in the functions for SSL:</p> @@ -72,7 +48,7 @@ <item><p><c>true | false</c></p></item> <tag><c>option() =</c></tag> - <item><p><c>socketoption() | ssloption() | transportoption()</c></p> + <item><p><c>socketoption() | ssl_option() | transport_option()</c></p> </item> <tag><c>socketoption() =</c></tag> @@ -84,11 +60,12 @@ <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> manual pages in Kernel.</p></item> - <tag><marker id="type-ssloption"></marker><c>ssloption() =</c></tag> + <tag><marker id="type-ssloption"/><c>ssl_option() =</c></tag> <item> <p><c>{verify, verify_type()}</c></p> <p><c>| {verify_fun, {fun(), term()}}</c></p> - <p><c>| {fail_if_no_peer_cert, boolean()} {depth, integer()}</c></p> + <p><c>| {fail_if_no_peer_cert, boolean()}</c></p> + <p><c>| {depth, integer()}</c></p> <p><c>| {cert, public_key:der_encoded()}</c></p> <p><c>| {certfile, path()}</c></p> <p><c>| {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' @@ -108,11 +85,11 @@ [binary()]} | {client | server, [binary()], binary()}}</c></p> <p><c>| {log_alert, boolean()}</c></p> <p><c>| {server_name_indication, hostname() | disable}</c></p> - <p><c>| {sni_hosts, [{hostname(), ssloptions()}]}</c></p> + <p><c>| {sni_hosts, [{hostname(), [ssl_option()]}]}</c></p> <p><c>| {sni_fun, SNIfun::fun()}</c></p> </item> - <tag><c>transportoption() =</c></tag> + <tag><c>transport_option() =</c></tag> <item><p><c>{cb_info, {CallbackModule::atom(), DataTag::atom(), ClosedTag::atom(), ErrTag:atom()}}</c></p> @@ -150,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 @@ -159,7 +136,7 @@ <tag><c>sslsocket() =</c></tag> <item><p>opaque()</p></item> - <tag><c>protocol() =</c></tag> + <tag><marker id="type-protocol"/><c>protocol() =</c></tag> <item><p><c>sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'</c></p></item> <tag><c>ciphers() =</c></tag> @@ -167,7 +144,9 @@ <p>According to old API.</p></item> <tag><c>ciphersuite() =</c></tag> - <item><p><c>{key_exchange(), cipher(), hash()}</c></p></item> + + <item><p><c>{key_exchange(), cipher(), MAC::hash()} | + {key_exchange(), cipher(), MAC::hash(), PRF::hash()}</c></p></item> <tag><c>key_exchange()=</c></tag> <item><p><c>rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk @@ -176,10 +155,10 @@ <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</c></p></item> + <item><p><c>md5 | sha | sha224 | sha256 | sha348 | sha512</c></p></item> <tag><c>prf_random() =</c></tag> <item><p><c>client_random | server_random</c></p></item> @@ -189,7 +168,15 @@ | srp_4096 | srp_6144 | srp_8192</c></p></item> <tag><c>SNIfun::fun()</c></tag> - <item><p><c>= fun(ServerName :: string()) -> ssloptions()</c></p></item> + <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> @@ -202,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> @@ -238,13 +230,18 @@ 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 <url href="http://www.ietf.org/rfc/rfc5746.txt">RFC 5746</url>. By default <c>secure_renegotiate</c> is set to <c>false</c>, that is, secure renegotiation is used if possible, - but it fallback to unsecure renegotiation if the peer + but it falls back to insecure renegotiation if the peer does not support <url href="http://www.ietf.org/rfc/rfc5746.txt">RFC 5746</url>.</p> </item> @@ -257,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> @@ -292,7 +289,11 @@ atom()}} | terminate regarding verification failures and the connection is established.</p></item> <item><p>If called with an extension unknown to the user application, - return value <c>{unknown, UserState}</c> is to be used.</p></item> + return value <c>{unknown, UserState}</c> is to be used.</p> + + <p>Note that if the fun returns <c>unknown</c> for an extension marked + as critical, validation will fail.</p> + </item> </list> <p>Default option <c>verify_fun</c> in <c>verify_peer mode</c>:</p> @@ -314,6 +315,8 @@ atom()}} | <code> {fun(_,{bad_cert, _}, UserState) -> {valid, UserState}; + (_,{extension, #'Extension'{critical = true}}, UserState) -> + {valid, UserState}; (_,{extension, _}, UserState) -> {unknown, UserState}; (_, valid, UserState) -> @@ -330,7 +333,7 @@ atom()}} | <tag><c>unknown_ca</c></tag> <item><p>No trusted CA was found in the trusted store. The trusted CA is normally a so called ROOT CA, which is a self-signed certificate. Trust can - be claimed for an intermediat CA (trusted anchor does not have to be + be claimed for an intermediate CA (trusted anchor does not have to be self-signed according to X-509) by using option <c>partial_chain</c>.</p> </item> @@ -346,39 +349,96 @@ 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 cerificate 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> + + <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> <tag><c>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | @@ -430,12 +490,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> + 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> - </taglist> + - <warning><p>Using <c>{padding_check, boolean()}</c> makes TLS - vulnerable to the Poodle attack.</p></warning> + <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> + + <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> + + <warning><p>Using <c>{beast_mitigation, disabled}</c> makes SSL or TLS + vulnerable to the BEAST attack.</p></warning> + </item> + </taglist> </section> @@ -479,8 +555,8 @@ fun(srp, Username :: string(), UserState :: term()) -> <p>The negotiated protocol can be retrieved using the <c>negotiated_protocol/1</c> function.</p> </item> - <tag><c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()]}}</c></tag> - <tag><c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()], Default :: binary()}}</c></tag> + <tag><c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()]}}</c><br/> + <c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()], Default :: binary()}}</c></tag> <item> <p>Indicates that the client is to try to perform Next Protocol Negotiation.</p> @@ -511,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> @@ -537,10 +621,43 @@ fun(srp, Username :: string(), UserState :: term()) -> be supported by the server for the prevention to work. </p></warning> </item> - - </taglist> + <tag><marker id="client_signature_algs"/><c>{signature_algs, [{hash(), ecdsa | rsa | dsa}]}</c></tag> + <item> + <p>In addition to the algorithms negotiated by the cipher + suite used for key exchange, payload encryption, message + authentication and pseudo random calculation, the TLS signature + algorithm extension <url + href="http://www.ietf.org/rfc/rfc5246.txt">Section 7.4.1.4.1 in RFC 5246</url> may be + used, from TLS 1.2, to negotiate which signature algorithm to use during the + 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</p> + + <code>[ +%% SHA2 +{sha512, ecdsa}, +{sha512, rsa}, +{sha384, ecdsa}, +{sha384, rsa}, +{sha256, ecdsa}, +{sha256, rsa}, +{sha224, ecdsa}, +{sha224, rsa}, +%% SHA +{sha, ecdsa}, +{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 + </p> + </item> + </taglist> </section> - + <section> <title>SSL OPTION DESCRIPTIONS - SERVER SIDE</title> @@ -633,20 +750,20 @@ fun(srp, Username :: string(), UserState :: term()) -> selection. If set to <c>false</c> (the default), use the client preference.</p></item> - <tag><c>{sni_hosts, [{hostname(), ssloptions()}]}</c></tag> + <tag><c>{sni_hosts, [{hostname(), [ssl_option()]}]}</c></tag> <item><p>If the server receives a SNI (Server Name Indication) from the client - matching a host listed in the <c>sni_hosts</c> option, the speicific options for + matching a host listed in the <c>sni_hosts</c> option, the specific options for that host will override previously specified options. The option <c>sni_fun</c>, and <c>sni_hosts</c> are mutually exclusive.</p></item> <tag><c>{sni_fun, SNIfun::fun()}</c></tag> <item><p>If the server receives a SNI (Server Name Indication) from the client, - the given function will be called to retrive <c>ssloptions()</c> for indicated server. - These options will be merged into predefined <c>ssloptions()</c>. + the given function will be called to retrieve <c>[ssl_option()]</c> for the indicated server. + These options will be merged into predefined <c>[ssl_option()]</c>. The function should be defined as: - <c>fun(ServerName :: string()) -> ssloptions()</c> + <c>fun(ServerName :: string()) -> [ssl_option()]</c> and can be specified as a fun or as named <c>fun module:function/1</c> The option <c>sni_fun</c>, and <c>sni_hosts</c> are mutually exclusive.</p></item> @@ -656,22 +773,36 @@ fun(srp, Username :: string(), UserState :: term()) -> of resources of such an operation is higher for the server than the client. This can act as a vector for denial of service attacks. The SSL application already takes measures to counter-act such attempts, - but client-initiated renegotiation can be stricly disabled by setting + but client-initiated renegotiation can be strictly disabled by setting this option to <c>false</c>. The default value is <c>true</c>. Note that disabling renegotiation can result in long-lived connections becoming unusable due to limits on the number of messages the underlying cipher suite can encipher. </item> - <tag><c>{psk_identity, string()}</c></tag> - <item>Specifies the server identity hint the server presents to the client. - </item> - <tag><c>{log_alert, boolean()}</c></tag> - <item>If false, error reports will not be displayed.</item> <tag><c>{honor_cipher_order, boolean()}</c></tag> <item>If true, use the server's preference for cipher selection. If false (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 + negotiation, introduced in TLS-1.2. The algorithms will also be offered to the client if a + 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> @@ -712,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> @@ -731,7 +873,7 @@ fun(srp, Username :: string(), UserState :: term()) -> equivalent, connected socket to an SSL socket.</fsummary> <type> <v>Socket = socket()</v> - <v>SslOptions = [ssloption()]</v> + <v>SslOptions = [ssl_option()]</v> <v>Timeout = integer() | infinity</v> <v>SslSocket = sslsocket()</v> <v>Reason = term()</v> @@ -770,18 +912,20 @@ fun(srp, Username :: string(), UserState :: term()) -> </func> <func> - <name>connection_info(SslSocket) -> - {ok, {ProtocolVersion, CipherSuite}} | {error, Reason}</name> - <fsummary>Returns the Negotiated Protocol version and cipher suite. - </fsummary> + <name>close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}</name> + <fsummary>Closes an SSL connection.</fsummary> <type> - <v>CipherSuite = ciphersuite()</v> - <v>ProtocolVersion = protocol()</v> + <v>SslSocket = sslsocket()</v> + <v>How = timeout() | {NewController::pid(), timeout()} </v> + <v>Reason = term()</v> </type> - <desc><p>Returns the Negotiated Protocol version and cipher suite.</p> + <desc><p>Closes or downgrades an SSL connection. In the latter case the transport + connection will be handed over to the <c>NewController</c> process after receiving + the TLS close alert from the peer. The returned transport socket will have + the following options set: <c>[{active, false}, {packet, 0}, {mode, binary}]</c></p> </desc> </func> - + <func> <name>controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}</name> @@ -800,40 +944,39 @@ fun(srp, Username :: string(), UserState :: term()) -> <func> <name>connection_information(SslSocket) -> - {ok, Info} | {error, Reason} </name> + {ok, Result} | {error, Reason} </name> <fsummary>Returns all the connection information. </fsummary> <type> - <v>Info = [InfoTuple]</v> - <v>InfoTuple = {protocol, Protocol} | {cipher_suite, CipherSuite} | {sni_hostname, SNIHostname}</v> - <v>CipherSuite = ciphersuite()</v> - <v>ProtocolVersion = protocol()</v> - <v>SNIHostname = string()</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>Return all the connection information containing negotiated protocol version, cipher suite, and the hostname of SNI extension. - Info will be a proplists containing all the connection information on success, otherwise <c>{error, Reason}</c> will be returned.</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> <func> <name>connection_information(SslSocket, Items) -> - {ok, Info} | {error, Reason} </name> + {ok, Result} | {error, Reason} </name> <fsummary>Returns the requested connection information. </fsummary> <type> - <v>Items = [Item]</v> - <v>Item = protocol | cipher_suite | sni_hostname</v> - <v>Info = [InfoTuple]</v> - <v>InfoTuple = {protocol, Protocol} | {cipher_suite, CipherSuite} | {sni_hostname, SNIHostname}</v> - <v>CipherSuite = ciphersuite()</v> - <v>ProtocolVersion = protocol()</v> - <v>SNIHostname = string()</v> + <v>Items = [Item]</v> + <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> - <desc><p>Returns the connection information you requested. The connection information you can request contains protocol, cipher_suite, and sni_hostname. - <c>{ok, Info}</c> will be returned if it executes sucessfully. The Info is a proplists containing the information you requested. - Otherwise, <c>{error, Reason}</c> will be returned.</p> + <desc><p>Returns the requested information items about the connection, + if they are defined.</p> + <note><p>If only undefined options are requested the + resulting list can be empty.</p></note> </desc> </func> @@ -863,6 +1006,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> @@ -1046,7 +1206,7 @@ fun(srp, Username :: string(), UserState :: term()) -> <fsummary>Performs server-side SSL/TLS handshake.</fsummary> <type> <v>Socket = socket() | sslsocket() </v> - <v>SslOptions = ssloptions()</v> + <v>SslOptions = [ssl_option()]</v> <v>Timeout = integer()</v> <v>Reason = term()</v> </type> @@ -1160,7 +1320,7 @@ fun(srp, Username :: string(), UserState :: term()) -> <seealso marker="#listen-2"> listen/2</seealso>, and <seealso marker="#ssl_accept-2">ssl_accept/[1,2,3]</seealso>. For the negotiated TLS/SSL version, see <seealso - marker="#connection_info-1">ssl:connection_info/1 + marker="#connection_information-1">ssl:connection_information/1 </seealso>.</item> <tag><c>available</c></tag> diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml index 2b6dc7e8be..f317dfded4 100644 --- a/lib/ssl/doc/src/ssl_app.xml +++ b/lib/ssl/doc/src/ssl_app.xml @@ -4,7 +4,7 @@ <appref> <header> <copyright> - <year>1999</year><year>2015</year> + <year>1999</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -33,7 +33,43 @@ <appsummary>The ssl application provides secure communication over sockets.</appsummary> - <description></description> + <description> + <p> + The ssl application is an implementation of the SSL/TLS protocol in Erlang. + </p> + <list type="bulleted"> + <item>Supported SSL/TLS-versions are SSL-3.0, TLS-1.0, + TLS-1.1, and TLS-1.2.</item> + <item>For security reasons SSL-2.0 is not supported.</item> + <item>For security reasons SSL-3.0 is no longer supported by default, + but can be configured.</item> + <item>For security reasons DES cipher suites are no longer supported by default, + but can be configured.</item> + <item> Renegotiation Indication Extension <url href="http://www.ietf.org/rfc/rfc5746.txt">RFC 5746</url> is supported + </item> + <item>Ephemeral Diffie-Hellman cipher suites are supported, + but not Diffie Hellman Certificates cipher suites.</item> + <item>Elliptic Curve cipher suites are supported if the Crypto + application supports it and named curves are used. + </item> + <item>Export cipher suites are not supported as the + U.S. lifted its export restrictions in early 2000.</item> + <item>IDEA cipher suites are not supported as they have + become deprecated by the latest TLS specification so it is not + motivated to implement them.</item> + <item>Compression is not supported.</item> + <item>CRL validation is supported.</item> + <item>Policy certificate extensions are not supported.</item> + <item>'Server Name Indication' extension + (<url href="http://www.ietf.org/rfc/rfc6066.txt">RFC 6066</url>) is supported.</item> + <item>Application Layer Protocol Negotiation (ALPN) and its successor Next Protocol Negotiation (NPN) + are supported. </item> + <item>It is possible to use Pre-Shared Key (PSK) and Secure Remote Password (SRP) + cipher suites, but they are not enabled by default. + </item> + </list> + </description> + <section> <title>DEPENDENCIES</title> <p>The SSL application uses the <c>public_key</c> and @@ -58,7 +94,7 @@ <p><c>erl -ssl protocol_version "['tlsv1.2', 'tlsv1.1']"</c></p> <taglist> - <tag><c><![CDATA[protocol_version = <seealso marker="kernel:error_logger">ssl:protocol()</seealso> <optional>]]></c>.</tag> + <tag><c>protocol_version = </c><seealso marker="ssl#type-protocol">ssl:protocol()</seealso><c><![CDATA[<optional>]]></c></tag> <item><p>Protocol supported by started clients and servers. If this option is not set, it defaults to all protocols currently supported by the SSL application. @@ -66,33 +102,73 @@ to <c>ssl:connect/[2,3]</c> and <c>ssl:listen/2</c>.</p></item> <tag><c><![CDATA[session_lifetime = integer() <optional>]]></c></tag> - <item><p>Lifetime of the session data in seconds.</p></item> + <item><p>Maximum lifetime of the session data in seconds. Defaults to 24 hours which is the maximum + recommended lifetime by <url href="http://www.ietf.org/rfc/5246rfc.txt">RFC 5246</url>. However + sessions may be invalidated earlier due to the maximum limitation of the session cache table. + </p></item> <tag><c><![CDATA[session_cb = atom() <optional>]]></c></tag> <item><p>Name of the session cache callback module that implements the <c>ssl_session_cache_api</c> behavior. Defaults to - <c>ssl_session_cache.erl</c>.</p></item> + <c>ssl_session_cache</c>.</p></item> <tag><c><![CDATA[session_cb_init_args = proplist:proplist() <optional>]]></c></tag> <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> + <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 + reached, the current cache entries will be invalidated + regardless of their remaining lifetime. Defaults to + 1000.</p></item> + + <tag> <c><![CDATA[session_cache_server_max = integer() <optional>]]></c></tag> + <item><p>Limits the growth of the servers session cache, that is + how many client sessions are cached by the server. If the + maximum number of sessions is reached, the current cache entries + will be invalidated regardless of their remaining + lifetime. Defaults to 1000.</p></item> <tag><c><![CDATA[ssl_pem_cache_clean = integer() <optional>]]></c></tag> <item> <p> - Number of milliseconds between PEM cache validations. + Number of milliseconds between PEM cache validations. Defaults to 2 minutes. </p> <seealso 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> + Number of milliseconds between sending of a fatal alert and + closing the connection. Waiting a little while improves the + peers chances to properly receiving the alert so it may + shutdown gracefully. Defaults to 5000 milliseconds. + </p> + </item> </taglist> </section> <section> <title>ERROR LOGGER AND EVENT HANDLERS</title> - <p>The SSL application uses the default <seealso marker="kernel:error_logger">OTP error logger</seealso> to log unexpected errors and TLS alerts. The logging of TLS alerts may be turned off with the <c>log_alert</c> option. </p> + <p>The SSL application uses the default <seealso + marker="kernel:error_logger">OTP error logger</seealso> to log + unexpected errors and TLS alerts. The logging of TLS alerts may be + turned off with the <c>log_alert</c> option. </p> </section> <section> diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml index 71c1c61fe8..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> @@ -76,17 +76,32 @@ </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> </type> - <desc> <p>Lookup the CRLs belonging to the distribution point <c> Distributionpoint</c>. </p> + <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. + 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> @@ -103,4 +118,4 @@ </desc> </func> </funcs> -</erlref>
\ No newline at end of file +</erlref> diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml index a347ce5ae6..61f88e3860 100644 --- a/lib/ssl/doc/src/ssl_distribution.xml +++ b/lib/ssl/doc/src/ssl_distribution.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2000</year><year>2013</year> + <year>2000</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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 @@ -98,6 +98,7 @@ {stdlib,"1.18"}, {crypto, "2.0.3"}, {public_key, "0.12"}, + {asn1, "4.0"}, {ssl, "5.0"} ]}. </code> @@ -196,6 +197,9 @@ Eshell V5.0 (abort with ^G) <item><c>password</c></item> <item><c>cacertfile</c></item> <item><c>verify</c></item> + <item><c>verify_fun</c> (write as <c>{Module, Function, InitialUserState}</c>)</item> + <item><c>crl_check</c></item> + <item><c>crl_cache</c> (write as Erlang term)</item> <item><c>reuse_sessions</c></item> <item><c>secure_renegotiate</c></item> <item><c>depth</c></item> @@ -203,6 +207,10 @@ Eshell V5.0 (abort with ^G) <item><c>ciphers</c> (use old string format)</item> </list> + <p>Note that <c>verify_fun</c> needs to be written in a different + form than the corresponding SSL option, since funs are not + accepted on the command line.</p> + <p>The server can also take the options <c>dhfile</c> and <c>fail_if_no_peer_cert</c> (also prefixed).</p> @@ -210,10 +218,6 @@ Eshell V5.0 (abort with ^G) initiates a connection to another node. <c>server_</c>-prefixed options are used when accepting a connection from a remote node.</p> - <p>More complex options, such as <c>verify_fun</c>, are currently not - available, but a mechanism to handle such options may be added in - a future release.</p> - <p>Raw socket options, such as <c>packet</c> and <c>size</c> must not be specified on the command line.</p> @@ -271,4 +275,27 @@ Eshell V5.0 (abort with ^G) <p>The <c>init:get_arguments()</c> call verifies that the correct arguments are supplied to the emulator.</p> </section> + + <section> + <title>Using SSL distribution over IPv6</title> + <p>It is possible to use SSL distribution over IPv6 instead of + IPv4. To do this, pass the option <c>-proto_dist inet6_tls</c> + instead of <c>-proto_dist inet_tls</c> when starting Erlang, + either on the command line or in the <c>ERL_FLAGS</c> environment + variable.</p> + + <p>An example command line with this option would look like this:</p> + <code type="none"> +$ erl -boot /home/me/ssl/start_ssl -proto_dist inet6_tls + -ssl_dist_opt server_certfile "/home/me/ssl/erlserver.pem" + -ssl_dist_opt server_secure_renegotiate true client_secure_renegotiate true + -sname ssl_test +Erlang (BEAM) emulator version 5.0 [source] + +Eshell V5.0 (abort with ^G) +(ssl_test@myhost)1> </code> + + <p>A node started in this way will only be able to communicate with + other nodes using SSL distribution over IPv6.</p> + </section> </chapter> diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml index bd9330056d..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 @@ -31,9 +31,13 @@ <module>ssl_session_cache_api</module> <modulesummary>TLS session cache API</modulesummary> - <description>Defines the API for the TLS session cache so - that the data storage scheme can be replaced by - defining a new callback module implementing this API.</description> + <description> + <p> + Defines the API for the TLS session cache so + that the data storage scheme can be replaced by + defining a new callback module implementing this API. + </p> + </description> <section> <title>DATA TYPES</title> @@ -58,8 +62,8 @@ </taglist> </section> - - <funcs> + + <funcs> <func> <name>delete(Cache, Key) -> _</name> @@ -130,7 +134,7 @@ </p> </desc> </func> - + <func> <name>select_session(Cache, PartialKey) -> [session()]</name> <fsummary>Selects sessions that can be reused.</fsummary> @@ -147,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> @@ -174,7 +193,7 @@ </p> </desc> </func> - - </funcs> - + + </funcs> + </erlref> diff --git a/lib/ssl/doc/src/usersguide.xml b/lib/ssl/doc/src/usersguide.xml index 7bd0ae5c4c..23ccf668c3 100644 --- a/lib/ssl/doc/src/usersguide.xml +++ b/lib/ssl/doc/src/usersguide.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2000</year><year>2013</year> + <year>2000</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml index b6a4bb5bec..f84cd6e391 100644 --- a/lib/ssl/doc/src/using_ssl.xml +++ b/lib/ssl/doc/src/using_ssl.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> |