aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssl/doc')
-rw-r--r--lib/ssl/doc/src/notes.xml230
-rw-r--r--lib/ssl/doc/src/ssl.xml134
-rw-r--r--lib/ssl/doc/src/ssl_distribution.xml23
3 files changed, 337 insertions, 50 deletions
diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml
index 61d1c8355a..1e8de1a8a3 100644
--- a/lib/ssl/doc/src/notes.xml
+++ b/lib/ssl/doc/src/notes.xml
@@ -28,6 +28,236 @@
<p>This document describes the changes made to the SSL application.</p>
+<section><title>SSL 7.3.3.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 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>
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index bf87644116..e831f73530 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -144,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
@@ -156,7 +158,7 @@
| aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm</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>
@@ -221,7 +223,7 @@
<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>
@@ -269,7 +271,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>
@@ -291,6 +297,8 @@ atom()}} |
<code>
{fun(_,{bad_cert, _}, UserState) ->
{valid, UserState};
+ (_,{extension, #'Extension'{critical = true}}, UserState) ->
+ {valid, UserState};
(_,{extension, _}, UserState) ->
{unknown, UserState};
(_, valid, UserState) ->
@@ -307,7 +315,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>
@@ -352,7 +360,7 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
<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>
+ marker="public_key:public_key_records"> X509 certificate extensions.</seealso>
Requires the OTP inets application.</p>
</item>
</taglist>
@@ -413,7 +421,6 @@ fun(srp, Username :: string(), UserState :: term()) ->
<warning><p>Using <c>{padding_check, boolean()}</c> makes TLS
vulnerable to the Poodle attack.</p></warning>
-
</section>
<section>
@@ -514,9 +521,45 @@ 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
+
+ <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},
+%% MD5
+{md5, rsa}
+]</code>
+
+ The algorithms should be in the preferred order.
+ Selected signature algorithm can restrict which hash functions
+ that may be selected.
+ </p>
+ </item>
+ </taglist>
</section>
-
+
<section>
<title>SSL OPTION DESCRIPTIONS - SERVER SIDE</title>
@@ -611,14 +654,14 @@ fun(srp, Username :: string(), UserState :: term()) ->
<tag><c>{sni_hosts, [{hostname(), ssloptions()}]}</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.
+ the given function will be called to retrieve <c>ssloptions()</c> for the indicated server.
These options will be merged into predefined <c>ssloptions()</c>.
The function should be defined as:
@@ -632,7 +675,7 @@ 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
@@ -643,6 +686,14 @@ fun(srp, Username :: string(), UserState :: term()) ->
<item>If true, use the server's preference for cipher 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>
+
</taglist>
</section>
@@ -748,26 +799,13 @@ fun(srp, Username :: string(), UserState :: term()) ->
<v>How = timeout() | {NewController::pid(), timeout()} </v>
<v>Reason = term()</v>
</type>
- <desc><p>Closes or downgrades an SSL connection, in the later case the transport
- connection will be handed over to the <c>NewController</c> process after reciving
- the TLS close alert from the peer. The retuned transport socket will have
- the following options set [{active, false}, {packet, 0}, {mode, binary}].</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>connection_info(SslSocket) ->
- {ok, {ProtocolVersion, CipherSuite}} | {error, Reason}</name>
- <fsummary>Returns the Negotiated Protocol version and cipher suite.
- </fsummary>
- <type>
- <v>CipherSuite = ciphersuite()</v>
- <v>ProtocolVersion = protocol()</v>
- </type>
- <desc><p>Returns the Negotiated Protocol version and cipher suite.</p>
- </desc>
- </func>
-
+
<func>
<name>controlling_process(SslSocket, NewOwner) ->
ok | {error, Reason}</name>
@@ -786,40 +824,36 @@ 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 | 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 all relevant information about the connection, ssl options that
+ are undefined will be filtered out.</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 | 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 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>
@@ -1146,7 +1180,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_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml
index a347ce5ae6..dc04d446b0 100644
--- a/lib/ssl/doc/src/ssl_distribution.xml
+++ b/lib/ssl/doc/src/ssl_distribution.xml
@@ -271,4 +271,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>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-29 20:54:03 +0000