diff options
Diffstat (limited to 'lib/ssl/doc/src')
| -rw-r--r-- | lib/ssl/doc/src/notes.xml | 356 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl.xml | 133 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_app.xml | 13 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl_protocol.xml | 2 |
4 files changed, 461 insertions, 43 deletions
diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml index 0b28b1ebd4..4349e5a456 100644 --- a/lib/ssl/doc/src/notes.xml +++ b/lib/ssl/doc/src/notes.xml @@ -25,7 +25,361 @@ <file>notes.xml</file> </header> <p>This document describes the changes made to the SSL application.</p> - <section><title>SSL 5.3.3</title> + <section><title>SSL 5.3.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Make sure the clean rule for ssh, ssl, eunit and otp_mibs + actually removes generated files.</p> + <p> + Own Id: OTP-12200</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Change code to reflect that state data may be secret to + avoid breaking dialyzer contracts.</p> + <p> + Own Id: OTP-12341</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 5.3.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Handle the fact that servers may send an empty SNI + extension to the client.</p> + <p> + Own Id: OTP-12198</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 5.3.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Corrected handling of ECC certificates, there where + several small issues with the handling of such + certificates in the ssl and public_key application. Now + ECC signed ECC certificates shall work and not only RSA + signed ECC certificates.</p> + <p> + Own Id: OTP-12026</p> + </item> + <item> + <p> + Check that the certificate chain ends with a trusted ROOT + CA e.i. a self-signed certificate, but provide an option + partial_chain to enable the application to define an + intermediat CA as trusted.</p> + <p> + Own Id: OTP-12149</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add decode functions for SNI (Server Name Indication)</p> + <p> + Own Id: OTP-12048</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 5.3.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + ssl:recv now returns {error, einval} if applied to a non + passive socket, the same as gen_tcp:recv. </p> + <p> + Thanks to Danil Zagoskin for reporting this issue</p> + <p> + Own Id: OTP-11878</p> + </item> + <item> + <p> + Corrected handling of default values for + signature_algorithms extension in TLS-1.2 and + corresponding values used in previous versions that does + not support this extension. </p> + <p> + Thanks to Danil Zagoskin</p> + <p> + Own Id: OTP-11886</p> + </item> + <item> + <p> + Handle socket option inheritance when pooling of accept + sockets is used</p> + <p> + Own Id: OTP-11897</p> + </item> + <item> + <p> + Make sure that the list of versions, possibly supplied in + the versions option, is not order dependent.</p> + <p> + Thanks to Ransom Richardson for reporting this issue</p> + <p> + Own Id: OTP-11912</p> + </item> + <item> + <p> + Reject connection if the next_protocol message is sent + twice.</p> + <p> + Own Id: OTP-11926</p> + </item> + <item> + <p> + Correct options handling when ssl:ssl_accept/3 is called + with new ssl options after calling ssl:listen/2</p> + <p> + Own Id: OTP-11950</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Gracefully handle unknown alerts</p> + <p> + Thanks to Atul Atri for reporting this issue</p> + <p> + Own Id: OTP-11874</p> + </item> + <item> + <p> + Gracefully ignore cipher suites sent by client not + supported by the SSL/TLS version that the client has + negotiated.</p> + <p> + Thanks to Danil Zagoskin for reporting this issue</p> + <p> + Own Id: OTP-11875</p> + </item> + <item> + <p> + Gracefully handle structured garbage, i.e a client sends + some garbage in a ssl record instead of a valid fragment.</p> + <p> + Thanks to Danil Zagoskin</p> + <p> + Own Id: OTP-11880</p> + </item> + <item> + <p> + Gracefully handle invalid alerts</p> + <p> + Own Id: OTP-11890</p> + </item> + <item> + <p> + Generalize handling of default ciphers</p> + <p> + Thanks to Andreas Schultz</p> + <p> + Own Id: OTP-11966</p> + </item> + <item> + <p> + Make sure change cipher spec is correctly handled</p> + <p> + Own Id: OTP-11975</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 5.3.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix incorrect dialyzer spec and types, also enhance + documentation. </p> + <p> + Thanks to Ayaz Tuncer.</p> + <p> + Own Id: OTP-11627</p> + </item> + <item> + <p> + Fix possible mismatch between SSL/TLS version and default + ciphers. Could happen when you specified SSL/TLS-version + in optionlist to listen or accept.</p> + <p> + Own Id: OTP-11712</p> + </item> + <item> + <p> + Application upgrade (appup) files are corrected for the + following applications: </p> + <p> + <c>asn1, common_test, compiler, crypto, debugger, + dialyzer, edoc, eldap, erl_docgen, et, eunit, gs, hipe, + inets, observer, odbc, os_mon, otp_mibs, parsetools, + percept, public_key, reltool, runtime_tools, ssh, + syntax_tools, test_server, tools, typer, webtool, wx, + xmerl</c></p> + <p> + A new test utility for testing appup files is added to + test_server. This is now used by most applications in + OTP.</p> + <p> + (Thanks to Tobias Schlager)</p> + <p> + Own Id: OTP-11744</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Moved elliptic curve definition from the crypto + NIF/OpenSSL into Erlang code, adds the RFC-5639 brainpool + curves and makes TLS use them (RFC-7027).</p> + <p> + Thanks to Andreas Schultz</p> + <p> + Own Id: OTP-11578</p> + </item> + <item> + <p> + Unicode adaptations</p> + <p> + Own Id: OTP-11620</p> + </item> + <item> + <p> + Added option honor_cipher_order. This instructs the + server to prefer its own cipher ordering rather than the + client's and can help protect against things like BEAST + while maintaining compatability with clients which only + support older ciphers. </p> + <p> + Thanks to Andrew Thompson for the implementation, and + Andreas Schultz for the test cases.</p> + <p> + Own Id: OTP-11621</p> + </item> + <item> + <p> + Replace boolean checking in validate_option with + is_boolean guard. </p> + <p> + Thanks to Andreas Schultz.</p> + <p> + Own Id: OTP-11634</p> + </item> + <item> + <p> + Some function specs are corrected or moved and some edoc + comments are corrected in order to allow use of edoc. + (Thanks to Pierre Fenoll)</p> + <p> + Own Id: OTP-11702</p> + </item> + <item> + <p> + Correct clean up of certificate database when certs are + inputed in pure DER format.The incorrect code could cause + a memory leek when certs where inputed in DER. Thanks to + Bernard Duggan for reporting this.</p> + <p> + Own Id: OTP-11733</p> + </item> + <item> + <p> + Improved documentation of the cacertfile option</p> + <p> + Own Id: OTP-11759 Aux Id: seq12535 </p> + </item> + <item> + <p> + Avoid next protocol negotiation failure due to incorrect + option format.</p> + <p> + Own Id: OTP-11760</p> + </item> + <item> + <p> + Handle v1 CRLs, with no extensions and fixes issues with + IDP (Issuing Distribution Point) comparison during CRL + validation. </p> + <p> + Thanks to Andrew Thompson</p> + <p> + Own Id: OTP-11761</p> + </item> + <item> + <p> + Server now ignores client ECC curves that it does not + support instead of crashing. </p> + <p> + Thanks to Danil Zagoskin for reporting the issue and + suggesting a solution.</p> + <p> + Own Id: OTP-11780</p> + </item> + <item> + <p> + Handle SNI (Server Name Indication) alert + unrecognized_name and gracefully deal with unexpected + alerts. </p> + <p> + Thanks to Masatake Daimon for reporting this.</p> + <p> + Own Id: OTP-11815</p> + </item> + <item> + <p> + Add possibility to specify ssl options when calling + ssl:ssl_accept</p> + <p> + Own Id: OTP-11837</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 5.3.3</title> <section><title>Fixed Bugs and Malfunctions</title> <list> diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 4bc1a9a644..249fee5760 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>2014</year> + <year>1999</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -163,7 +163,7 @@ is supplied it will override the certfile option.</item> <tag>{certfile, path()}</tag> - <item>Path to a file containing the user's certificate.</item> + <item>Path to a file containing the user's PEM encoded certificate.</item> <tag>{key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo', der_encoded()}}</tag> <item> The DER encoded users private key. If this option @@ -226,7 +226,7 @@ <p>The verification fun should be defined as:</p> <code> -fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | +fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} | {extension, #'Extension'{}}, InitialUserState :: term()) -> {valid, UserState :: term()} | {valid_peer, UserState :: term()} | {fail, Reason :: term()} | {unknown, UserState :: term()}. @@ -252,7 +252,7 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | always returns {valid, UserState}, the TLS/SSL handshake will not be terminated with respect to verification failures and the connection will be established. If called with an - extension unknown to the user application the return value + extension unknown to the user application, the return value {unknown, UserState} should be used.</p> <p>The default verify_fun option in verify_peer mode:</p> @@ -283,9 +283,29 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | end, []} </code> -<p>Possible path validation errors: </p> + <p>Possible path validation errors are given on the form {bad_cert, Reason} where Reason is:</p> + + <taglist> + <tag>unknown_ca</tag> + <item>No trusted CA was found in the trusted store. The trusted CA is + normally a so called ROOT CA that is a self-signed cert. Trust may + be claimed for an intermediat CA (trusted anchor does not have to be self signed + according to X-509) by using the option <c>partial_chain</c></item> + + <tag>selfsigned_peer</tag> + <item>The chain consisted only of one self-signed certificate.</item> + + <tag>PKIX X-509-path validation error</tag> + <item> Possible such reasons see <seealso + marker="public_key:public_key#pkix_path_validation-3"> public_key:pkix_path_validation/3 </seealso></item> + </taglist> -<p> {bad_cert, cert_expired}, {bad_cert, invalid_issuer}, {bad_cert, invalid_signature}, {bad_cert, unknown_ca},{bad_cert, selfsigned_peer}, {bad_cert, name_not_permitted}, {bad_cert, missing_basic_constraint}, {bad_cert, invalid_key_usage}</p> + </item> + + <tag>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | unknown_ca </tag> + <item> + Claim an intermediat CA in the chain as trusted. TLS will then perform the public_key:pkix_path_validation/3 + with the selected CA as trusted anchor and the rest of the chain. </item> <tag>{versions, [protocol()]}</tag> @@ -328,11 +348,23 @@ fun(srp, Username :: string(), UserState :: term()) -> </p> </item> + <tag>{padding_check, boolean()}</tag> + <item> + <p> This option only affects TLS-1.0 connections. + If set to false it disables the block cipher padding check + to be able to interoperate with legacy software. + </p> + + <warning><p> Using this option makes TLS vulnerable to + the Poodle attack</p></warning> + + </item> + </taglist> - + </section> - - <section> + + <section> <title>SSL OPTION DESCRIPTIONS - CLIENT SIDE</title> <p>Options described here are client specific or has a slightly different @@ -518,7 +550,19 @@ fun(srp, Username :: string(), UserState :: term()) -> </p> </desc> </func> - + + <func> + <name>clear_pem_cache() -> ok </name> + <fsummary> Clears the pem cache</fsummary> + + <desc><p>PEM files, used by ssl API-functions, are cached. The + cache is regularly checked to see if any cache entries should be + invalidated, however this function provides a way to + unconditionally clear the whole cache. + </p> + </desc> + </func> + <func> <name>connect(Socket, SslOptions) -> </name> <name>connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} @@ -768,39 +812,45 @@ fun(srp, Username :: string(), UserState :: term()) -> </func> <func> - <name>ssl_accept(ListenSocket) -> </name> - <name>ssl_accept(ListenSocket, Timeout) -> ok | {error, Reason}</name> - <fsummary>Perform server-side SSL handshake</fsummary> + <name>ssl_accept(Socket) -> </name> + <name>ssl_accept(Socket, Timeout) -> ok | {error, Reason}</name> + <fsummary>Perform server-side SSL/TLS handshake</fsummary> <type> - <v>ListenSocket = sslsocket()</v> + <v>Socket = sslsocket()</v> <v>Timeout = integer()</v> <v>Reason = term()</v> </type> <desc> - <p>The <c>ssl_accept</c> function establish the SSL connection - on the server side. It should be called directly after - <c>transport_accept</c>, in the spawned server-loop.</p> + <p> Performs the SSL/TLS server-side handshake <c>Socket</c> is a socket as returned + by <seealso + marker="#transport_accept-2">ssl:transport_accept/[1,2]</seealso> + </p> </desc> </func> <func> - <name>ssl_accept(ListenSocket, SslOptions) -> </name> - <name>ssl_accept(ListenSocket, SslOptions, Timeout) -> {ok, Socket} | {error, Reason}</name> - <fsummary>Perform server-side SSL handshake</fsummary> + <name>ssl_accept(Socket, SslOptions) -> </name> + <name>ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}</name> + <fsummary>Perform server-side SSL/TLS handshake</fsummary> <type> - <v>ListenSocket = socket()</v> + <v>Socket = socket() | sslsocket() </v> <v>SslOptions = ssloptions()</v> <v>Timeout = integer()</v> <v>Reason = term()</v> </type> <desc> - <p> Upgrades a gen_tcp, or - equivalent, socket to an ssl socket i.e. performs the - ssl server-side handshake.</p> + <p> If <c>Socket</c> is a socket() - upgrades a gen_tcp, or equivalent, socket to an ssl socket + i.e. performs the SSL/TLS server-side handshake and returns the ssl socket. + </p> + <warning><p>Note that the listen socket should be in {active, false} mode before telling the client that the server is ready to upgrade - and calling this function, otherwise the upgrade may + by calling this function, otherwise the upgrade may or may not succeed depending on timing.</p></warning> + + <p> If <c>Socket</c> is an sslsocket() - provides additional SSL/TLS options to those specified in <seealso + marker="#listen-2">ssl:listen/2 </seealso> and then performs the SSL/TLS handshake. + </p> </desc> </func> @@ -842,33 +892,38 @@ fun(srp, Username :: string(), UserState :: term()) -> </func> <func> - <name>transport_accept(Socket) -></name> - <name>transport_accept(Socket, Timeout) -> + <name>transport_accept(ListenSocket) -></name> + <name>transport_accept(ListenSocket, Timeout) -> {ok, NewSocket} | {error, Reason}</name> <fsummary>Accept an incoming connection and prepare for <c>ssl_accept</c></fsummary> <type> - <v>Socket = NewSocket = sslsocket()</v> + <v>ListenSocket = NewSocket = sslsocket()</v> <v>Timeout = integer()</v> <v>Reason = reason()</v> </type> <desc> <p>Accepts an incoming connection request on a listen socket. - <c>ListenSocket</c> must be a socket returned from - <c>listen/2</c>. The socket returned should be passed to - <c>ssl_accept</c> to complete ssl handshaking and - establishing the connection.</p> + <c>ListenSocket</c> must be a socket returned from + <seealso + marker="#listen-2"> ssl:listen/2</seealso>. + The socket returned should be passed to + <seealso marker="#ssl_accept-2"> ssl:ssl_accept[2,3]</seealso> + to complete handshaking i.e + establishing the SSL/TLS connection.</p> <warning> - <p>The socket returned can only be used with <c>ssl_accept</c>, - no traffic can be sent or received before that call.</p> + <p>The socket returned can only be used with + <seealso marker="#ssl_accept-2"> ssl:ssl_accept[2,3]</seealso> + no traffic can be sent or received before that call.</p> </warning> <p>The accepted socket inherits the options set for - <c>ListenSocket</c> in <c>listen/2</c>.</p> + <c>ListenSocket</c> in <seealso + marker="#listen-2"> ssl:listen/2</seealso>.</p> <p>The default - value for <c>Timeout</c> is <c>infinity</c>. If - <c>Timeout</c> is specified, and no connection is accepted - within the given time, <c>{error, timeout}</c> is - returned.</p> + value for <c>Timeout</c> is <c>infinity</c>. If + <c>Timeout</c> is specified, and no connection is accepted + within the given time, <c>{error, timeout}</c> is + returned.</p> </desc> </func> diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml index 43cb3934f7..f1377cabda 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>2013</year> + <year>1999</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -82,7 +82,16 @@ callback module, defaults to []. </p> </item> - + + <tag><c><![CDATA[ssl_pem_cache_clean = integer() <optional>]]></c></tag> + <item> + <p> + Number of milliseconds between PEM cache validations. + </p> + <seealso + marker="ssl#clear_pem_cache-0">ssl:clear_pem_cache/0</seealso> + + </item> </taglist> </section> diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml index cdfafe224b..80d9cc4ee8 100644 --- a/lib/ssl/doc/src/ssl_protocol.xml +++ b/lib/ssl/doc/src/ssl_protocol.xml @@ -83,7 +83,7 @@ <em>subject</em>. The certificate is signed with the private key of the issuer of the certificate. A chain of trust is build by having the issuer in its turn being - certified by an other certificate and so on until you reach the + certified by another certificate and so on until you reach the so called root certificate that is self signed i.e. issued by itself.</p> |