diff options
Diffstat (limited to 'lib/ssl/doc/src/ssl.xml')
| -rw-r--r-- | lib/ssl/doc/src/ssl.xml | 204 |
1 files changed, 182 insertions, 22 deletions
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 803c0f789a..b4a30a68c8 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>2022</year> + <year>1999</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -229,6 +229,10 @@ </datatype> <datatype> + <name name="legacy_named_curve"/> + </datatype> + + <datatype> <name name="psk_identity"/> </datatype> @@ -473,16 +477,10 @@ {sha384, ecdsa}, {sha384, rsa}, {sha256, ecdsa}, -{sha256, rsa}, -{sha224, ecdsa}, -{sha224, rsa}, -%% SHA -{sha, ecdsa}, -{sha, rsa}, -{sha, dsa} +{sha256, rsa} ]</code> -<p>Support for {md5, rsa} was removed from the the TLS-1.2 default in ssl-8.0 (OTP-22) </p> +<p>Support for {md5, rsa} was removed from the the TLS-1.2 default in ssl-8.0 (OTP-22) and support for SHA1 {sha, _} and SHA224 {sha224, _} was removed in ssl-11.0 (OTP-26) </p> <p><c> rsa_pss_schemes =</c></p> <code> @@ -500,8 +498,6 @@ rsa_pss_rsae_sha256] rsa_pkcs1_sha512, %% Corresponds to {sha512, rsa} rsa_pkcs1_sha384, %% Corresponds to {sha384, rsa} rsa_pkcs1_sha256, %% Corresponds to {sha256, rsa} -ecdsa_sha1, %% Corresponds to {sha, ecdsa} -rsa_pkcs1_sha1 %% Corresponds to {sha, rsa} ] </code> @@ -520,13 +516,13 @@ ecdsa_secp256r1_sha256] ++ rsa_pss_schemes() </code> - <p>EDDSA was made highest priority in ssl-11.0 (OTP-25) </p> + <p>EDDSA was made highest priority in ssl-10.8 (OTP-25) </p> <p>TLS-1.3 default is</p> -<code>Default_TLS_13_Schemes ++ Legacy_TLS_13_Schemes </code> +<code>Default_TLS_13_Schemes</code> <p>If both TLS-1.3 and TLS-1.2 are supported the default will be</p> -<code>Default_TLS_13_Schemes ++ Default_TLS_12_Alg_Pairs </code> +<code>Default_TLS_13_Schemes ++ TLS_13_Legacy_Schemes ++ Default_TLS_12_Alg_Pairs (not represented in TLS_13_Legacy_Schemes) </code> <p>so appropriate algorithms can be chosen for the negotiated version. @@ -821,7 +817,7 @@ marker="public_key:public_key#pkix_path_validation/3">public_key:pkix_path_valid <desc> <code> fun(Chain::[public_key:der_encoded()]) -> - {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca} + {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca. </code> <p>Claim an intermediate CA in the chain as trusted. TLS then performs <seemfa @@ -1160,7 +1156,10 @@ fun(srp, Username :: binary(), UserState :: term()) -> <name name="customize_hostname_check"/> <desc> <p> Customizes the hostname verification of the peer certificate, as different protocols that use - TLS such as HTTP or LDAP may want to do it differently, for possible options see + TLS such as HTTP or LDAP may want to do it differently. For example the get standard HTTPS handling + provide the already implememnted fun from the public_key application for HTTPS. + <c>{customize_hostname_check, [{match_fun, public_key:pkix_verify_hostname_match_fun(https)}]}</c> + For futher description of customize options see <seemfa marker="public_key:public_key#pkix_verify_hostname/3">public_key:pkix_verify_hostname/3</seemfa> </p> </desc> </datatype> @@ -1231,6 +1230,34 @@ fun(srp, Username :: binary(), UserState :: term()) -> </desc> </datatype> + <datatype> + <name name="use_srtp"/> + <desc> + <p>Configures the <c>use_srtp</c> DTLS hello extension.</p> + <p>In order to negotiate the use of SRTP data protection, clients + include an extension of type "use_srtp" in the DTLS extended client + hello. This extension MUST only be used when the data being + transported is RTP or RTCP.</p> + <p>The value is a map with a mandatory <c>protection_profiles</c> and + an optional <c>mki</c> parameters.</p> + <p><c>protection_profiles</c> configures the list of the client's acceptable + SRTP Protection Profiles. Each profile is a 2-byte binary. Example: + <c>#{protection_profiles => [<<0,2>>, <<0,5>>]}</c></p> + <p><c>mki</c> configures the SRTP Master Key Identifier chosen by the client.</p> + <p>The srtp_mki field contains the value of the SRTP MKI which is associated + with the SRTP master keys derived from this handshake. Each SRTP + session MUST have exactly one master key that is used to protect + packets at any given time. The client MUST choose the MKI value so + that it is distinct from the last MKI value that was used, and it + SHOULD make these values unique for the duration of the TLS session.</p> + <note><p>This extension MUST only be used with DTLS, and not with TLS.</p></note> + <note><p>OTP does not handle SRTP, so an external implementations of SRTP + encoder/decoder and a packet demultiplexer are needed to make use + of the <c>use_srtp</c> extension. See also + <seetype marker="#transport_option">cb_info</seetype> option.</p></note> + </desc> + </datatype> + <!-- <datatype> --> <!-- <name name="ocsp_stapling"/> --> <!-- <desc><p>If true, OCSP stapling will be enabled, an extension of type "status_request" will be --> @@ -1472,15 +1499,34 @@ fun(srp, Username :: binary(), UserState :: term()) -> <datatype> <name name="server_session_tickets"/> <desc> - <p>Configures the session ticket functionality. Allowed values are <c>disabled</c>, - <c>stateful</c> and <c>stateless</c>.</p> - <p>If it is set to <c>stateful</c> or - <c>stateless</c>, session resumption with pre-shared keys is enabled and the server will - send stateful or stateless session tickets to the client after successful connections.</p> + <p>Configures the session ticket functionality. Allowed values are <c>disabled</c>, + <c>stateful</c>, <c>stateless</c>, <c>stateful_with_cert</c>, <c>stateless_with_cert</c>.</p> + <p>If it is not set to <c>disabled</c>, + session resumption with pre-shared keys is enabled and the server will + send stateful or stateless session tickets to the client after successful connections.</p> + + <note><p> + Pre-shared key session ticket resumption does not include any certificate exchange, + hence the function <seemfa marker="ssl:ssl#peercert/1">ssl:peercert/1</seemfa> will not + be able to return the peer certificate as it is only communicated in the initial handshake. + The server options <c>stateful_with_cert</c> or <c>stateless_with_cert</c> may be used + to make a server associate the client certificate from the original handshake + with the tickets it issues. + </p></note> + <p>A stateful session ticket is a database reference to internal state information. A stateless session ticket is a self-encrypted binary that contains both cryptographic keying material and state data. </p> + + <warning><p> + If it is set to <c>stateful_with_cert</c> the client certificate + is stored with the internal state information, increasing memory consumption. + If it is set to <c>stateless_with_cert</c> the client certificate is + encoded in the self-encrypted binary that is sent to the client, + increasing the payload size. + </p></warning> + <note><p>This option is supported by TLS 1.3 and above. See also <seeguide marker="ssl:using_ssl#session-tickets-and-session-resumption-in-tls-1.3"> SSL's Users Guide, Session Tickets and Session Resumption in TLS 1.3</seeguide> @@ -1489,6 +1535,26 @@ fun(srp, Username :: binary(), UserState :: term()) -> </datatype> <datatype> + <name name="stateless_tickets_seed"/> + <desc> + <p>Configures the seed used for the encryption of stateless session tickets. + Allowed values are any randomly generated <c>binary()</c>. If this option is not + configured, an encryption seed will be randomly generated.</p> + + <warning><p>Reusing the ticket encryption seed between multiple server + instances enables stateless session tickets to work across multiple server + instances, but it breaks anti-replay protection across instances.</p> + + <p>Inaccurate time synchronization between server instances can also + affect session ticket freshness checks, potentially causing false negatives as + well as false positives.</p></warning> + + <note><p>This option is supported by TLS 1.3 and above and only with stateless + session tickets.</p></note> + </desc> + </datatype> + + <datatype> <name name="anti_replay"/> <desc> <p>Configures the server's built-in anti replay feature based on Bloom filters.</p> @@ -1496,7 +1562,7 @@ fun(srp, Username :: binary(), UserState :: term()) -> <p>Allowed values are the pre-defined <c>'10k'</c>, <c>'100k'</c> or a custom 3-tuple that defines the properties of the bloom filters: <c>{WindowSize, HashFunctions, Bits}</c>. <c>WindowSize</c> is the number of seconds after the current Bloom filter is rotated - and also the window size used for freshness checks. <c>HashFunctions</c> is the number + and also the window size used for freshness checks of ClientHello. <c>HashFunctions</c> is the number hash functions and <c>Bits</c> is the number of bits in the bit vector. <c>'10k'</c> and <c>'100k'</c> are simple defaults with the following properties:</p> <list type="bulleted"> @@ -1544,6 +1610,40 @@ fun(srp, Username :: binary(), UserState :: term()) -> </datatype> <datatype> + <name name="use_srtp"/> + <desc> + <p>Configures the <c>use_srtp</c> DTLS hello extension.</p> + <p>Servers that receive an extended hello containing a "use_srtp" + extension can agree to use SRTP by including an extension of type + "use_srtp", with the chosen protection profile in the extended server + hello. This extension MUST only be used when the data being + transported is RTP or RTCP.</p> + <p>The value is a map with a mandatory <c>protection_profiles</c> and + an optional <c>mki</c> parameters.</p> + <list type="bulleted"> + <item><p><c>protection_profiles</c> configures the list of the server's chosen + SRTP Protection Profile as a list of a single 2-byte binary. Example: + <c>#{protection_profiles => [<<0,5>>]}</c></p></item> + <item><p><c>mki</c> configures the server's SRTP Master Key Identifier.</p> + <p>Upon receipt of a "use_srtp" extension containing a "srtp_mki" field, + the server MUST either (assuming it accepts the extension at all):</p> + <list type="bulleted"> + <item><p>include a matching "srtp_mki" value in its "use_srtp" extension + to indicate that it will make use of the MKI, or</p></item> + <item><p>return an empty "srtp_mki" value to indicate that it cannot + make use of the MKI (default).</p></item> + </list> + </item> + </list> + <note><p>This extension MUST only be used with DTLS, and not with TLS.</p></note> + <note><p>OTP does not handle SRTP, so an external implementations of SRTP + encoder/decoder and a packet demultiplexer are needed to make use + of the <c>use_srtp</c> extension. See also + <seetype marker="#transport_option">cb_info</seetype> option.</p></note> + </desc> + </datatype> + + <datatype> <name name="connection_info"/> </datatype> @@ -2019,6 +2119,12 @@ fun(srp, Username :: binary(), UserState :: term()) -> <c>{error, renegotiation_rejected}</c> indicating that the peer refused to go through with the renegotiation, but the connection is still active using the previously negotiated session.</p> + <p>TLS-1.3 has removed the renegotiate feature of earlier TLS versions + and instead adds a new feature called key update that replaces the most + important part of renegotiate, that is the refreshing of session keys. + This is triggered automatically after reaching a plaintext limit and + can be configured by option <seetype marker="ssl:ssl#key_update_at">key_update_at</seetype>. + </p> </desc> </func> @@ -2067,6 +2173,60 @@ fun(srp, Username :: binary(), UserState :: term()) -> is useful.</p> </desc> </func> + + <func> + <name since="OTP @OTP-18572@" name="signature_algs" arity="2" /> + <fsummary>Returns a list of signature algorithms/schemes </fsummary> + <desc> + <p>Lists all possible signature algorithms corresponding to + <c>Description</c> that are available. The + <c>exclusive</c> option will exclusively list + algorithms/schemes for that protocol version, whereas the + <c>default</c> and <c>all</c> options lists the combined list to support the + range of protocols from (D)TLS-1.2, the first version to support + configuration of the signature algorithms, to <c>Version</c>.</p> + + <p> Example: <c> + + 1> ssl:signature_algs(default, 'tlsv1.3'). + [eddsa_ed25519,eddsa_ed448,ecdsa_secp521r1_sha512, + ecdsa_secp384r1_sha384,ecdsa_secp256r1_sha256, + rsa_pss_pss_sha512,rsa_pss_pss_sha384,rsa_pss_pss_sha256, + rsa_pss_rsae_sha512,rsa_pss_rsae_sha384,rsa_pss_rsae_sha256, + rsa_pkcs1_sha512,rsa_pkcs1_sha384,rsa_pkcs1_sha256, + {sha512,ecdsa}, + {sha384,ecdsa}, + {sha256,ecdsa}] + + 2>ssl:signature_algs(all, 'tlsv1.3'). + [eddsa_ed25519,eddsa_ed448,ecdsa_secp521r1_sha512, + ecdsa_secp384r1_sha384,ecdsa_secp256r1_sha256, + rsa_pss_pss_sha512,rsa_pss_pss_sha384,rsa_pss_pss_sha256, + rsa_pss_rsae_sha512,rsa_pss_rsae_sha384,rsa_pss_rsae_sha256, + rsa_pkcs1_sha512,rsa_pkcs1_sha384,rsa_pkcs1_sha256, + {sha512,ecdsa}, + {sha384,ecdsa}, + {sha256,ecdsa}, + {sha224,ecdsa}, + {sha224,rsa}, + {sha,rsa}, + {sha,dsa}] + + 3> ssl:signature_algs(exclusive, 'tlsv1.3'). + [eddsa_ed25519,eddsa_ed448,ecdsa_secp521r1_sha512, + ecdsa_secp384r1_sha384,ecdsa_secp256r1_sha256, + rsa_pss_pss_sha512,rsa_pss_pss_sha384,rsa_pss_pss_sha256, + rsa_pss_rsae_sha512,rsa_pss_rsae_sha384,rsa_pss_rsae_sha256] + </c></p> + + <note><p>Some TLS-1-3 scheme names overlap with TLS-1.2 + algorithm-tuple-pair-names and then TLS-1.3 names will be + used, for example <c>rsa_pkcs1_sha256</c> instead of + <c>{sha256, rsa}</c> these are legacy algorithms in TLS-1.3 + that apply only to certificate signatures in this version of + the protocol.</p></note> + </desc> + </func> <func> <name since="" name="sockname" arity="1" /> |