View Source ssl (ssl v11.2.1)
Interface functions for TLS (Transport Layer Security), and DTLS (Datagram Transport Layer Security).
Note
The applications name is still SSL due to the fact that the first versions of the TLS protcol were named SSL (Secure Socket Layer), however, no version of the old SSL protocol are supported, by this application.
Example:
1> ssl:start(), ssl:connect("google.com", 443, [{verify, verify_peer},
{cacerts, public_key:cacerts_get()}]).
{ok,{sslsocket, [...]}}
See Using SSL for detailed usage and more examples of this API.
Special Erlang node configuration for the application can be found in ssl application reference.
Summary
Types: Socket
When a TLS/DTLS socket is in active mode (the default), data from the socket is delivered to the owner of the socket in the form of messages.
DTLS protocol version that for security reason no longer are supported by default.
DTLS protocol version.
If a TLS connection fails a TLS protocol ALERT will be sent/received.
A name or address to a host.
Client hello extensions.
TLS or DTLS protocol version.
Error reason for debug purpose should not be matched.
Identifies a TLS session pre TLS-1.3.
Socket that can be used to perform a so called "START-TLS", that is use an already connected socket that was previously used for plain TCP traffic and can be upgraded to use TLS. Both sides needs to agree on the upgrade.
Options for the transport socket.
An opaque reference to the TLS/DTLS connection, however it may be used for equality matching.
TLS Alert Protocol reasons.
All options that can be supplied to a TLS client
TLS protocol version that for security reason no longer are supported by default.
Option related to the TLS/DTLS protocol.
All options that can be supplied to a TLS server
TLS protocol version.
Transport option defines a callback module and message tags to handle the underlying transport socket.
Types: Algorithms
Cipher algorithms that can be used for payload encryption.
Filter that allows you to customize cipher suite list.
A list of cipher suites that should be supported
Cipher suite formats.
Erlang cipher suite representation
TLS-1.3 key exchange configuration.
Hash algorithms used together with signing and encryption functions.
Cipher Suite Key Exchange Algorithm will be any in TLS-1.3 as key exchange is no longer part of cipher suite configuration in TLS-1.3.
Pre TLS-1.3 key exchange configuration.
Supported in TLS-1.3 and TLS-1.2.
SHA2 hash algorithms.
Signature algorithms.
Signature schemes, defined by TLS-1.3, and replaces signature algorithms from TLS-1.2.
Explicitly list acceptable signature algorithms for certificates and handshake messages in the preferred order.
Pre TLS-1.3 SRP cipher suite configuration.
Types: Certificates
Claim an intermediate CA in the chain as trusted.
Configuration of the entity certificate and its corresponding key.
Options for using built in CRL cache support.
The user's private key.
Types: Algorithms Legacy
Cipher algorithms that for security reason no longer are supported by default.
Hash algorithms that for security reason no longer are supported by default
Pre TLS-1.3 key exchange configuration. These curves has been deprecated by RFC 8422.
Signature algorithms that for security reasons no longer are supported by default
Only used for certificate signatures if TLS-1.2 is negotiated, that is the peer only supports TLS-1.2 but we support also TLS-1.3.
For backwards compatibility only, do not use it.
Types: Info
Key value list convening some information about the established connection.
TLS connection keys that you can get information about.
TLS connection information relevant pre TLS-1.3.
TLS connection information that can be used for NSS-keyloging.
Types: Deprecated
Server API
Performs the TLS/DTLS server-side handshake.
Performs the TLS/DTLS server-side handshake.
Performs the TLS/DTLS server-side handshake.
Creates an SSL listen socket.
Accepts an incoming connection request on a listen socket.
Client and Server API
Closes a TLS/DTLS connection.
Closes or downgrades a TLS connection.
Assigns a new controlling process to the SSL socket.
Cancel the handshake with a fatal USER_CANCELED
alert.
Equivalent to handshake_continue(HsSocket, Options, infinity)
.
Continue the TLS handshake, possibly with new, additional or changed options.
Equivalent to recv(Socket, Length, infinity)
.
Receives a packet from a socket in passive mode.
Writes Data
to SslSocket
.
Sets options according to Options
for socket SslSocket
.
Immediately closes a socket in one or two directions.
TLS-1.3 Only API
Returns all supported groups in TLS 1.3. Existed since OTP 22.0 , documented as of OTP 27.
Returns default supported groups in TLS 1.3. Existed since OTP 22.0, documented as of OTP 27.
Create new session keys.
Pre TLS-1.3 API
Returns a list of all supported elliptic curves, including legacy curves, for all TLS/DTLS versions pre TLS-1.3.
Returns the by default supported elliptic curves for Version, which is a subset of what [eccs/[0]] returns.
Initiates a new handshake.
Utility Functions
Make Deferred
suites become the least preferred suites.
Lists all possible cipher suites corresponding to Description
that are
available.
Same as cipher_suites/2
but lists RFC or OpenSSL string names instead of
erl_cipher_suite/0
Clears the PEM cache.
Returns the most relevant information about the connection.
Returns the requested information items about the connection, if they are defined.
Equivalent to
export_key_materials(TLSSocket, Labels, Contexts, WantedLengths, true).
Uses the Pseudo-Random Function, PRF (pre TLS-1.3) or HKDF (TLS-1.3), for a TLS connection to generate and export keying materials.
Removes cipher suites if any of the filter functions returns false for any part of the cipher suite.
Presents the error returned by an SSL function as a printable string, the error tag may be both included and excluded
Gets the values of the specified socket options.
Equivalent to getstat/2
.
Gets one or more statistic options for the underlying TCP socket.
Returns the protocol negotiated through ALPN or NPN extensions.
The peer certificate is returned as a DER-encoded binary.
Returns the address and port number of the peer.
Make Preferred
suites become the most preferred suites.
Lists all possible signature algorithms corresponding to Description
that are
available.
Returns the local address and port number of socket SslSocket
.
Equivalent to start(temporary)
.
Starts the SSL application.
Stops the SSL application.
Converts an RFC or OpenSSL name string to an erl_cipher_suite/0
Converts erl_cipher_suite/0
to OpenSSL name string.
Converts an erl_cipher_suite()
value to an RFC
name string.
Lists information, mainly concerning TLS/DTLS versions, in runtime for debugging and testing purposes.
Deprecated API
Uses the Pseudo-Random Function (PRF) of a TLS session to generate extra key material.
Types: Socket
-type active_msgs() :: {ssl, sslsocket(), Data :: binary() | list()} | {ssl_closed, sslsocket()} | {ssl_error, sslsocket(), Reason :: any()} | {ssl_passive, sslsocket()}.
When a TLS/DTLS socket is in active mode (the default), data from the socket is delivered to the owner of the socket in the form of messages.
The ssl_passive
message is sent only when the socket is in {active, N}
mode
and the counter dropped to 0. It indicates that the socket has transitioned to
passive ({active, false}
) mode.
-type dtls_legacy_version() :: dtlsv1.
DTLS protocol version that for security reason no longer are supported by default.
-type dtls_version() :: 'dtlsv1.2' | dtls_legacy_version().
DTLS protocol version.
If a TLS connection fails a TLS protocol ALERT will be sent/received.
An atom reflecting the raised alert, according to the TLS protocol, and a description string with some further details will be returned.
-type host() :: inet:hostname() | inet:ip_address().
A name or address to a host.
-type protocol_extensions() :: #{renegotiation_info => binary(), signature_algs => signature_algs(), alpn => binary(), srp => binary(), next_protocol => binary(), max_frag_enum => 1..4, ec_point_formats => [0..2], elliptic_curves => [public_key:oid()], sni => inet:hostname()}.
Client hello extensions.
-type protocol_version() :: tls_version() | dtls_version().
TLS or DTLS protocol version.
-type reason() :: term().
Error reason for debug purpose should not be matched.
-type session_id() :: binary().
Identifies a TLS session pre TLS-1.3.
-type socket() :: gen_tcp:socket().
Socket that can be used to perform a so called "START-TLS", that is use an already connected socket that was previously used for plain TCP traffic and can be upgraded to use TLS. Both sides needs to agree on the upgrade.
-type socket_option() :: gen_tcp:connect_option() | gen_tcp:listen_option() | gen_udp:option().
Options for the transport socket.
The default socket options are
[{mode,list},{packet, 0},{header, 0},{active, true}]
.
For valid options, see the inet
, gen_tcp
and gen_udp
manual pages in Kernel. Note that stream oriented options such as packet are
only relevant for TLS and not DTLS.
-type sslsocket() :: any().
An opaque reference to the TLS/DTLS connection, however it may be used for equality matching.
-type tls_alert() ::
close_notify | unexpected_message | bad_record_mac | record_overflow | handshake_failure |
bad_certificate | unsupported_certificate | certificate_revoked | certificate_expired |
certificate_unknown | illegal_parameter | unknown_ca | access_denied | decode_error |
decrypt_error | export_restriction | protocol_version | insufficient_security |
internal_error | inappropriate_fallback | user_canceled | no_renegotiation |
unsupported_extension | certificate_unobtainable | unrecognized_name |
bad_certificate_status_response | bad_certificate_hash_value | unknown_psk_identity |
no_application_protocol.
TLS Alert Protocol reasons.
-type tls_client_option() :: client_option() | common_option() | socket_option() | transport_option().
All options that can be supplied to a TLS client
-type tls_legacy_version() :: tlsv1 | 'tlsv1.1'.
TLS protocol version that for security reason no longer are supported by default.
-type tls_option() :: tls_client_option() | tls_server_option().
Option related to the TLS/DTLS protocol.
-type tls_server_option() :: server_option() | common_option() | socket_option() | transport_option().
All options that can be supplied to a TLS server
-type tls_version() :: 'tlsv1.2' | 'tlsv1.3' | tls_legacy_version().
TLS protocol version.
-type transport_option() :: {cb_info, {CallbackModule :: atom(), DataTag :: atom(), ClosedTag :: atom(), ErrTag :: atom()}} | {cb_info, {CallbackModule :: atom(), DataTag :: atom(), ClosedTag :: atom(), ErrTag :: atom(), PassiveTag :: atom()}}.
Transport option defines a callback module and message tags to handle the underlying transport socket.
Can be used to customize the transport layer. The tag values should be the values used by the underlying transport in its active mode messages.
Defaults to {gen_tcp, tcp, tcp_closed, tcp_error, tcp_passive}
for TLS (for
backward compatibility a four tuple will be converted to a five tuple with the
last element "second_element"_passive) and
{gen_udp, udp, udp_closed, udp_error, udp_passive}
For TLS the callback module must implement a reliable transport
protocol, behave as gen_tcp
, and have functions corresponding to
inet:setopts/2
, inet:getopts/2
, inet:peername/1
, inet:sockname/1
, and
inet:port/1
. The callback gen_tcp
is treated specially and calls inet
directly. For DTLS this feature must be considered experimental.
Types: Algorithms
-type cipher() :: aes_256_gcm | aes_128_gcm | aes_256_ccm | aes_128_ccm | chacha20_poly1305 | aes_256_ccm_8 | aes_128_ccm_8 | aes_128_cbc | aes_256_cbc | legacy_cipher().
Cipher algorithms that can be used for payload encryption.
-type cipher_filters() :: [{key_exchange | cipher | mac | prf, fun((kex_algo() | cipher() | hash() | aead | default_prf) -> true | false)}].
Filter that allows you to customize cipher suite list.
-type cipher_suites() :: ciphers().
A list of cipher suites that should be supported
The function ssl:cipher_suites/2 can be used to find all cipher suites that are supported by default and all cipher suites that may be configured.
If you compose your own cipher_suites/0
make sure they are filtered for
cryptolib support
ssl:filter_cipher_suites/2 Additionally the
functions ssl:append_cipher_suites/2 ,
ssl:prepend_cipher_suites/2,
ssl:suite_to_str/1, ssl:str_to_suite/1,
and ssl:suite_to_openssl_str/1 also exist to help
creating customized cipher suite lists.
Note
Note that TLS-1.3 and TLS-1.2 cipher suites are not overlapping sets of cipher suites. To support both these versions cipher suites from both versions need to be included. Also if the supplied list does not comply with the configured versions or cryptolib so that the list becomes empty, this option will fallback on its appropriate default value for the configured versions.
Non-default cipher suites including anonymous cipher suites (PRE TLS-1.3) are
supported for interop/testing purposes and may be used by adding them to your
cipher suite list. Note that they must also be supported/enabled by the peer to
actually be used. The may also requier additional configuration see srp_param_type/0
.
-type ciphers() :: [erl_cipher_suite()] | string().
Cipher suite formats.
For backwards compatibility cipher suites can configured as a : separated string
of cipher suite RFC names (or even old OpenSSL names) althogh the more
flexible way is to use uitility functions together with cipher_filters/0
if a customized cipher suite option is needed.
-type erl_cipher_suite() :: #{key_exchange := kex_algo(), cipher := cipher(), mac := hash() | aead, prf := hash() | default_prf}.
Erlang cipher suite representation
Warning
Enabling cipher suites using RSA as a key exchange algorithm is strongly discouraged (only available pre TLS-1.3). For some configurations software preventions may exist, and can make them usable if they work, but relying on them to work is risky and there are many more reliable cipher suites that can be used instead.
-type group() ::
x25519 | x448 | secp256r1 | secp384r1 | secp521r1 | ffdhe2048 | ffdhe3072 | ffdhe4096 |
ffdhe6144 | ffdhe8192.
TLS-1.3 key exchange configuration.
-type hash() :: sha2() | legacy_hash().
Hash algorithms used together with signing and encryption functions.
-type kex_algo() ::
ecdhe_ecdsa | ecdh_ecdsa | ecdh_rsa | rsa | dhe_rsa | dhe_dss | srp_rsa | srp_dss | dhe_psk |
rsa_psk | psk | ecdh_anon | dh_anon | srp_anon | any.
Cipher Suite Key Exchange Algorithm will be any in TLS-1.3 as key exchange is no longer part of cipher suite configuration in TLS-1.3.
-type named_curve() :: x25519 | x448 | secp521r1 | brainpoolP512r1 | brainpoolP384r1 | secp384r1 | brainpoolP256r1 | secp256r1 | legacy_named_curve().
Pre TLS-1.3 key exchange configuration.
-type rsassa_pss_scheme() ::
rsa_pss_rsae_sha512 | rsa_pss_rsae_sha384 | rsa_pss_rsae_sha256 | rsa_pss_pss_sha512 |
rsa_pss_pss_sha384 | rsa_pss_pss_sha256.
Supported in TLS-1.3 and TLS-1.2.
-type sha2() :: sha512 | sha384 | sha256.
SHA2 hash algorithms.
-type sign_algo() :: eddsa | ecdsa | rsa | legacy_sign_algo().
Signature algorithms.
-type sign_scheme() :: eddsa_ed25519 | eddsa_ed448 | ecdsa_secp521r1_sha512 | ecdsa_secp384r1_sha384 | ecdsa_secp256r1_sha256 | ecdsa_brainpoolP512r1tls13_sha512 | ecdsa_brainpoolP384r1tls13_sha384 | ecdsa_brainpoolP256r1tls13_sha256 | rsassa_pss_scheme() | legacy_sign_scheme().
Signature schemes, defined by TLS-1.3, and replaces signature algorithms from TLS-1.2.
Explicitly list acceptable signature schemes in the preferred order.
Overrides the algorithms supplied in
signature_algs
option for certificates.
In addition to the signature_algorithms
extension from TLS 1.2,
TLS 1.3 (RFC 5246 Section 4.2.3)
adds the signature_algorithms_cert
extension which enables having special
requirements on the signatures used in the certificates that differs from the
requirements on digital signatures as a whole. If this is not required this
extension is not need.
The client will send a signature_algorithms_cert
extension (in the
client hello message), if TLS version 1.2 (back-ported to TLS 1.2 in
24.1) or later is used, and the signature_algs_cert option is
explicitly specified. By default, only the
signature_algs extension is sent with the
exception of when signature_algs option is not explicitly specified,
in which case it will append the rsa_pkcs1_sha1 algorithm to the
default value of signature_algs and use it as value for
signature_algs_cert to allow certificates to have this signature but
still disallow sha1 use in the TLS protocol, since 27.0.1 and 26.2.5.2.
Note
Note that supported signature schemes for TLS-1.2 are
legacy_sign_scheme/0
andrsassa_pss_scheme/0
-type signature_algs() :: [{hash(), sign_algo()} | sign_scheme()].
Explicitly list acceptable signature algorithms for certificates and handshake messages in the preferred order.
The client will send its list as the client
hello signature_algorithm
extension introduced in TLS-1.2, see
Section 7.4.1.4.1 in RFC 5246. Previously
these algorithms where implicitly chosen and partly derived from the cipher
suite.
In TLS-1.2 a somewhat more explicit negotiation is made possible using a list of
{hash/0
, sign_algo/0
} pairs.
In TLS-1.3 these algorithm pairs are replaced by so called signature schemes
sign_scheme/0
and completely decoupled from the cipher suite.
Signature algorithms used for certificates may be overridden by the
[signature schemes] supplied by the
signature_algs_cert
option.
TLS-1.2 default is Default_TLS_12_Alg_Pairs interleaved with rsa_pss_schemes since ssl-11.0 (OTP 25) pss_pss is prefered over pss_rsae that is prefered over rsa
Default_TLS_12_Alg_Pairs =
[
%% SHA2
{sha512, ecdsa},
{sha512, rsa},
{sha384, ecdsa},
{sha384, rsa},
{sha256, ecdsa},
{sha256, rsa}
]
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)
rsa_pss_schemes =
[rsa_pss_pss_sha512,
rsa_pss_pss_sha384,
rsa_pss_pss_sha256,
rsa_pss_rsae_sha512,
rsa_pss_rsae_sha384,
rsa_pss_rsae_sha256]
TLS_13_Legacy_Schemes =
[
%% Legacy algorithms only applicable to certificate signatures
rsa_pkcs1_sha512, %% Corresponds to {sha512, rsa}
rsa_pkcs1_sha384, %% Corresponds to {sha384, rsa}
rsa_pkcs1_sha256, %% Corresponds to {sha256, rsa}
]
Default_TLS_13_Schemes =
[
%% EDDSA
eddsa_ed25519,
eddsa_ed448
%% ECDSA
ecdsa_secp521r1_sha512,
ecdsa_secp384r1_sha384,
ecdsa_secp256r1_sha256] ++
%% RSASSA-PSS
rsa_pss_schemes()
EDDSA was made highest priority in ssl-10.8 (OTP 25)
TLS-1.3 default is
Default_TLS_13_Schemes
If both TLS-1.3 and TLS-1.2 are supported the default will be
Default_TLS_13_Schemes ++ TLS_13_Legacy_Schemes ++
Default_TLS_12_Alg_Pairs (not represented in TLS_13_Legacy_Schemes)
so appropriate algorithms can be chosen for the negotiated version.
Note
TLS-1.2 algorithms will not be negotiated for TLS-1.3, but TLS-1.3 RSASSA-PSS
rsassa_pss_scheme/0
signature schemes may be negotiated also for TLS-1.2 from 24.1 (fully working from 24.1.3). However if TLS-1.3 is negotiated when both TLS-1.3 and TLS-1.2 is supported using defaults, the corresponding TLS-1.2 algorithms to the TLS-1.3 legacy signature schemes will be considered as the legacy schemes and applied only to certificate signatures.
-type srp_param_type() :: srp_8192 | srp_6144 | srp_4096 | srp_3072 | srp_2048 | srp_1536 | srp_1024.
Pre TLS-1.3 SRP cipher suite configuration.
Types: Certificates
-type anchor_fun() :: fun().
Claim an intermediate CA in the chain as trusted.
fun(Chain::[public_key:der_encoded()]) ->
{trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca.
TLS then performs public_key:pkix_path_validation/3
with the selected CA as trusted anchor and
the rest of the chain.
-type cert_key_conf() :: #{cert => public_key:der_encoded() | [public_key:der_encoded()], key => key(), certfile => file:filename(), keyfile => file:filename(), password => iodata() | fun(() -> iodata())}.
Configuration of the entity certificate and its corresponding key.
A certificate (or possibly a list of the certificate and its chain certificates where the entity certificate must be the first element in the list or first entry in the file) and its associated key on one of the possible formats. For the PEM file format there may also be a password associated with the file containg the key.
For maximum interoperability the certificates in the chain should be in the correct order, the chain will be sent as is to the peer. If chain certificates are not provided, certificates from the configured trusted CA-certs are used to construct the chain. See certificate options for the client and server
Options for using built in CRL cache support.
Specify how to perform lookup and caching of certificate revocation lists.
Module
defaults to ssl_crl_cache
with DbHandle
being internal
and an
empty argument list.
There are two implementations available:
ssl_crl_cache
- Implementation 1This module maintains a cache of CRLs. CRLs can be added to the cache using the function
ssl_crl_cache:insert/1
, and optionally automatically fetched through HTTP if the following argument is specified:{http, timeout()}
Enables fetching of CRLs specified as http URIs inX509 certificate extensions. Requires the OTP inets application.
ssl_crl_hash_dir
- Implementation 2This module makes use of a directory where CRLs are stored in files named by the hash of the issuer name.
The file names consist of eight hexadecimal digits followed by
.rN
, whereN
is an integer, e.g.1a2b3c4d.r0
. For the first version of the CRL,N
starts at zero, and for each new version,N
is incremented by one. The OpenSSL utilityc_rehash
creates symlinks according to this pattern.For a given hash value, this module finds all consecutive
.r*
files starting from zero, and those files taken together make up the revocation list. CRL files whosenextUpdate
fields are in the past, or that are issued by a different CA that happens to have the same name hash, are excluded.The following argument is required:
{dir, string()}
Specifies the directory in which the CRLs can be found.
-type key() :: {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()} | #{algorithm := sign_algo(), engine := crypto:engine_ref(), key_id := crypto:key_id(), password => crypto:password()} | #{algorithm := sign_algo(), sign_fun := fun(), sign_opts => list(), encrypt_fun => fun(), encrypt_opts => list()}.
The user's private key.
Either the key can be provided directly as DER encoded entity, or indirectly using a crypto engine/provider (with key reference information) or an Erlang fun (with possible custom options). The latter two options can both be used for customized signing with for instance hardware security modules (HSM) or trusted platform modules (TPM).
- A DER encoded key will need to specify the ASN-1 type used to create the encoding.
- An engine/provider needs to specify specific information to support this concept and can optionally be password protected, see also crypto:engine_load/3 and Crypto's Users Guide.
- A fun option should include a fun that mimics
public_key:sign/4
and possibly public_key:private_encrypt/4 if legacy versions TLS-1.0 and TLS-1.1 should be supported.
Types: Algorithms Legacy
-type legacy_cipher() :: '3des_ede_cbc' | des_cbc | rc4_128.
Cipher algorithms that for security reason no longer are supported by default.
-type legacy_hash() :: sha224 | sha | md5.
Hash algorithms that for security reason no longer are supported by default
-type legacy_named_curve() ::
sect571r1 | sect571k1 | sect409k1 | sect409r1 | sect283k1 | sect283r1 | secp256k1 |
sect239k1 | sect233k1 | sect233r1 | secp224k1 | secp224r1 | sect193r1 | sect193r2 |
secp192k1 | secp192r1 | sect163k1 | sect163r1 | sect163r2 | secp160k1 | secp160r1 | secp160r2.
Pre TLS-1.3 key exchange configuration. These curves has been deprecated by RFC 8422.
-type legacy_sign_algo() :: dsa.
Signature algorithms that for security reasons no longer are supported by default
-type legacy_sign_scheme() ::
rsa_pkcs1_sha512 | rsa_pkcs1_sha384 | rsa_pkcs1_sha256 | ecdsa_sha1 | rsa_pkcs1_sha1.
Only used for certificate signatures if TLS-1.2 is negotiated, that is the peer only supports TLS-1.2 but we support also TLS-1.3.
-type old_cipher_suite() :: {kex_algo(), cipher(), hash()} | {kex_algo(), cipher(), hash() | aead, hash()}.
For backwards compatibility only, do not use it.
Types: Client Options
Types: Server Options
Types: Client and Server Options
Types: Info
-type connection_info() :: [{protocol, protocol_version()} | {session_resumption, boolean()} | {selected_cipher_suite, erl_cipher_suite()} | {sni_hostname, term()} | {ciphers, [erl_cipher_suite()]}] | connection_info_pre_tls13() | security_info().
Key value list convening some information about the established connection.
-type connection_info_keys() ::
[protocol | selected_cipher_suite | sni_hostname | session_resumption | ciphers |
client_random | server_random | master_secret | keylog | session_id | session_data | ecc |
srp_username].
TLS connection keys that you can get information about.
-type connection_info_pre_tls13() :: [{session_id, session_id()} | {session_data, binary()} | {ecc, {named_curve, term()}} | {srp_username, term()}].
TLS connection information relevant pre TLS-1.3.
-type security_info() :: [{client_random, binary()} | {server_random, binary()} | {master_secret, binary()} | {keylog, term()}].
TLS connection information that can be used for NSS-keyloging.
Types: Deprecated
-type prf_random() :: client_random | server_random.
Client API
-spec connect(TCPSocket, TLSOptions) -> {ok, sslsocket()} | {error, reason()} | {option_not_a_key_value_tuple, any()} when TCPSocket :: socket(), TLSOptions :: [tls_client_option()].
Equivalent to connect(TCPSocket, TLSOptions, infinity)
.
-spec connect(TCPSocketOrHost, TLSOptionsOrPort, TimeoutOrTLSOptions) -> {ok, sslsocket()} | {ok, sslsocket(), Ext :: protocol_extensions()} | {error, reason()} | {option_not_a_key_value_tuple, any()} when TCPSocketOrHost :: socket() | host(), TLSOptionsOrPort :: [tls_client_option()] | inet:port_number(), TimeoutOrTLSOptions :: [tls_client_option()] | timeout().
Opens a TLS/DTLS connection.
connect(TCPSocket, TLSOptions, Timeout).
Upgrades a gen_tcp
, or equivalent, connected socket to a TLS socket, that is,
performs the client-side TLS handshake.
connect(Host, Port, TLSOptions).
Opens a TLS/DTLS connection and is equivalent to
connect(Host, Port, TLSOptions, infinity).
-spec connect(Host, Port, TLSOptions, Timeout) -> {ok, sslsocket()} | {ok, sslsocket(), Ext :: protocol_extensions()} | {error, reason()} | {option_not_a_key_value_tuple, any()} when Host :: host(), Port :: inet:port_number(), TLSOptions :: [tls_client_option()], Timeout :: timeout().
Opens a TLS/DTLS connection to Host
, Port
.
When the option verify
is set to verify_peer
the check
public_key:pkix_verify_hostname/2
will be performed in addition to the usual
x509-path validation checks. If the check fails the error {bad_cert,
hostname_check_failed} will be propagated to the path validation fun
verify_fun
, where it is possible to do customized checks
by using the full possibilities of the public_key:pkix_verify_hostname/3
API.
When the option server_name_indication
is provided, its value (the DNS name)
will be used as ReferenceID
to public_key:pkix_verify_hostname/2
. When no
server_name_indication
option is given, the Host
argument will be used as
Server Name Indication extension. The Host
argument will also be used for the
public_key:pkix_verify_hostname/2
check and if the Host
argument is an
inet:ip_address()
the ReferenceID
used for the
check will be {ip, Host}
otherwise dns_id
will be assumed with a fallback to
ip
if that fails.
Note
According to good practices certificates should not use IP-addresses as "server names". It would be very surprising if this happened outside a closed network.
If the option {handshake, hello}
is used the handshake is paused after
receiving the server hello message and the success response is
{ok, SslSocket, Ext}
instead of {ok, SslSocket}
. Thereafter the handshake is
continued or canceled by calling handshake_continue/3
or handshake_cancel/1
.
If the option active
is set to once
, true
or an integer value, the process
owning the sslsocket will receive messages of type active_msgs/0
Server API
-spec handshake(HsSocket) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} when HsSocket :: sslsocket(), SslSocket :: sslsocket(), Ext :: protocol_extensions(), Reason :: closed | timeout | error_alert().
Performs the TLS/DTLS server-side handshake.
hanshake(HsSocket).
Is equivalent to:
handshake(HsSocket, infinity).
-spec handshake(HsSocket, OptionsOrTimeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} when HsSocket :: sslsocket(), OptionsOrTimeout :: timeout() | [server_option()], SslSocket :: sslsocket(), Ext :: protocol_extensions(), Reason :: closed | timeout | error_alert().
Performs the TLS/DTLS server-side handshake.
hanshake(HsSocket, Timeout).
Is equivalent to:
handshake(HsSocket, [], Timeout).
and,
hanshake(HsSocket, Options).
is equivalent to:
handshake(HsSocket, Options, infinity).
-spec handshake(Socket, Options, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} when Socket :: socket() | sslsocket(), SslSocket :: sslsocket(), Options :: [server_option()], Timeout :: timeout(), Ext :: protocol_extensions(), Reason :: closed | timeout | {options, any()} | error_alert().
Performs the TLS/DTLS server-side handshake.
Returns a new TLS/DTLS socket if the handshake is successful.
If Socket
is a ordinary socket/0
: upgrades a gen_tcp
, or equivalent,
socket to an SSL socket, that is, performs the TLS server-side handshake and
returns a TLS socket.
Note
The ordinary
Socket
shall be in passive mode ({active, false}) before calling this function, and before the client tries to connect with TLS, or else the behavior of this function is undefined. The best way to ensure this is to create the ordinary listen socket in passive mode.
If Socket
is an sslsocket() : provides extra TLS/DTLS
options to those specified in listen/2
and then performs the TLS/DTLS
handshake. Returns a new TLS/DTLS socket if the handshake is successful.
Warning
Not setting the timeout makes the server more vulnerable to DoS attacks.
If option {handshake, hello}
is specified the handshake is paused after
receiving the client hello message and the success response is
{ok, SslSocket, Ext}
instead of {ok, SslSocket}
. Thereafter the handshake is
continued or canceled by calling handshake_continue/3
or handshake_cancel/1
.
If the option active
is set to once
, true
or an integer value, the process
owning the sslsocket will receive messages of type active_msgs/0
-spec listen(Port, Options) -> {ok, ListenSocket} | {error, reason()} when Port :: inet:port_number(), Options :: [tls_server_option()], ListenSocket :: sslsocket().
Creates an SSL listen socket.
-spec transport_accept(ListenSocket) -> {ok, SslSocket} | {error, reason()} when ListenSocket :: sslsocket(), SslSocket :: sslsocket().
Equivalent to transport_accept(ListenSocket, infinity)
.
-spec transport_accept(ListenSocket, Timeout) -> {ok, SslSocket} | {error, reason()} when ListenSocket :: sslsocket(), Timeout :: timeout(), SslSocket :: sslsocket().
Accepts an incoming connection request on a listen socket.
ListenSocket
must be a socket returned from listen/2
. The socket
returned is to be passed to handshake/1,2,3 to
complete handshaking, that is, establishing the TLS/DTLS connection.
Warning
Most API functions require that the TLS/DTLS connection is established to work as expected.
The accepted socket inherits the options set for ListenSocket
in listen/2
.
The default value for Timeout
is infinity
. If Timeout
is specified and no
connection is accepted within the given time, {error, timeout}
is returned.
Client and Server API
Closes a TLS/DTLS connection.
-spec close(SslSocket, How) -> ok | {ok, port()} | {ok, port(), Data} | {error, Reason} when SslSocket :: sslsocket(), How :: timeout() | {NewController :: pid(), timeout()}, Data :: binary(), Reason :: any().
Closes or downgrades a TLS connection.
In the latter case the transport connection will be handed over to the
NewController
process after receiving the TLS close alert from the
peer. The returned transport socket will have the following options
set: [{active, false}, {packet, 0}, {mode, binary}]
.
In case of downgrade, the close function might return some binary data that should be treated by the user as the first bytes received on the downgraded connection.
-spec controlling_process(SslSocket, NewOwner) -> ok | {error, Reason} when SslSocket :: sslsocket(), NewOwner :: pid(), Reason :: any().
Assigns a new controlling process to the SSL socket.
A controlling process is the owner of an SSL socket, and receives all messages from the socket.
Cancel the handshake with a fatal USER_CANCELED
alert.
-spec handshake_continue(HsSocket, Options) -> {ok, SslSocket} | {error, Reason} when HsSocket :: sslsocket(), Options :: [tls_client_option() | tls_server_option()], SslSocket :: sslsocket(), Reason :: closed | timeout | error_alert().
Equivalent to handshake_continue(HsSocket, Options, infinity)
.
-spec handshake_continue(HsSocket, Options, Timeout) -> {ok, SslSocket} | {error, Reason} when HsSocket :: sslsocket(), Options :: [tls_client_option() | tls_server_option()], Timeout :: timeout(), SslSocket :: sslsocket(), Reason :: closed | timeout | error_alert().
Continue the TLS handshake, possibly with new, additional or changed options.
-spec recv(SslSocket, Length) -> {ok, Data} | {error, reason()} when SslSocket :: sslsocket(), Length :: non_neg_integer(), Data :: binary() | list() | HttpPacket, HttpPacket :: any().
Equivalent to recv(Socket, Length, infinity)
.
-spec recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()} when SslSocket :: sslsocket(), Length :: non_neg_integer(), Data :: binary() | list() | HttpPacket, Timeout :: timeout(), HttpPacket :: any().
Receives a packet from a socket in passive mode.
A closed socket is indicated by return value {error, closed}
.
Argument Length
is meaningful only when the socket is in mode raw
and denotes the number of bytes to read. If Length
= 0, all
available bytes are returned. If Length
> 0, exactly Length
bytes
are returned, or an error; possibly discarding less than Length
bytes of data when the socket gets closed from the other side.
Optional argument Timeout
specifies a time-out in milliseconds. The default
value is infinity
.
-spec send(SslSocket, Data) -> ok | {error, reason()} when SslSocket :: sslsocket(), Data :: iodata().
Writes Data
to SslSocket
.
A notable return value is {error, closed}
indicating that the socket is
closed.
-spec setopts(SslSocket, Options) -> ok | {error, reason()} when SslSocket :: sslsocket(), Options :: [gen_tcp:option()].
Sets options according to Options
for socket SslSocket
.
-spec shutdown(SslSocket, How) -> ok | {error, reason()} when SslSocket :: sslsocket(), How :: read | write | read_write.
Immediately closes a socket in one or two directions.
How == write
means closing the socket for writing, reading from it is still
possible.
To be able to handle that the peer has done a shutdown on the write side, option
{exit_on_close, false}
is useful.
TLS-1.3 Only API
-spec groups() -> [group()].
Returns all supported groups in TLS 1.3. Existed since OTP 22.0 , documented as of OTP 27.
-spec groups(Description) -> [group()] when Description :: default.
Returns default supported groups in TLS 1.3. Existed since OTP 22.0, documented as of OTP 27.
-spec update_keys(SslSocket, Type) -> ok | {error, reason()} when SslSocket :: sslsocket(), Type :: write | read_write.
Create new session keys.
There are cryptographic limits on the amount of plaintext which can be safely
encrypted under a given set of keys. If the amount of data surpasses those
limits, a key update is triggered and a new set of keys are installed. See also
the option key_update_at part of common_option_tls13/0
.
This function can be used to explicitly start a key update on a TLS 1.3 connection. There are two types of the key update: if Type is set to write, only the writing key is updated; if Type is set to read_write, both the reading and writing keys are updated.
Pre TLS-1.3 API
-spec eccs() -> NamedCurves when NamedCurves :: [named_curve()].
Returns a list of all supported elliptic curves, including legacy curves, for all TLS/DTLS versions pre TLS-1.3.
-spec eccs(Version) -> NamedCurves when Version :: 'tlsv1.2' | 'tlsv1.1' | tlsv1 | 'dtlsv1.2' | dtlsv1, NamedCurves :: [named_curve()].
Returns the by default supported elliptic curves for Version, which is a subset of what [eccs/[0]] returns.
Initiates a new handshake.
A notable return value is {error, renegotiation_rejected}
indicating
that the peer refused to go through with the renegotiation, but the
connection is still active using the previously negotiated session.
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
key_update_at part of common_option_tls13/0
.
Utility Functions
-spec append_cipher_suites(Deferred, Suites) -> ciphers() when Deferred :: ciphers() | cipher_filters(), Suites :: ciphers().
Make Deferred
suites become the least preferred suites.
That is put them at the end of the cipher suite list Suites
after
removing them from Suites
if present. Deferred
may be a list of
cipher suites or a list of filters in which case the filters are use
on Suites
to extract the Deferred cipher list.
-spec cipher_suites(Description, Version) -> ciphers() when Description :: default | all | exclusive | anonymous | exclusive_anonymous, Version :: protocol_version().
Lists all possible cipher suites corresponding to Description
that are
available.
The exclusive
and exclusive_anonymous
option will exclusively
list cipher suites first supported in Version
whereas the other options are
inclusive from the lowest possible version to Version
. The all
options
includes all suites except the anonymous and no anonymous suites are supported
by default.
Note
TLS-1.3 has no overlapping cipher suites with previous TLS versions, that is the result of
cipher_suites(all, 'tlsv1.3').
contains a separate set of suites that can be used with TLS-1.3 an other set that can be used if a lower version is negotiated. PRE TLS-1.3 so calledPSK
andSRP
suites need extra configuration to work that is the optionuser_lookup_function
. No anonymous suites are supported by TLS-1.3.Also note that the cipher suites returned by this function are the cipher suites that the OTP ssl application can support provided that they are supported by the cryptolib linked with the OTP crypto application. Use ssl:filter_cipher_suites(Suites, []). to filter the list for the current cryptolib. Note that cipher suites may be filtered out because they are too old or too new depending on the cryptolib.
-spec cipher_suites(Description, Version, StringType) -> [string()] when Description :: default | all | exclusive | anonymous, Version :: protocol_version(), StringType :: rfc | openssl.
Same as cipher_suites/2
but lists RFC or OpenSSL string names instead of
erl_cipher_suite/0
-spec clear_pem_cache() -> ok.
Clears the PEM cache.
PEM files, used by ssl API-functions, are cached for performance reasons. The cache is automatically checked at regular intervals to see if any cache entries should be invalidated.
This function provides a way to unconditionally clear the entire cache, thereby forcing a reload of previously cached PEM files.
-spec connection_information(SslSocket) -> {ok, Result} | {error, reason()} when SslSocket :: sslsocket(), Result :: connection_info().
Returns the most relevant information about the connection.
Some items 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.
Note
The legacy
Item = cipher_suite
was removed in OTP 23. Previously it returned the cipher suite on its (undocumented) legacy format. It is replaced byselected_cipher_suite
.
-spec connection_information(SslSocket, Items) -> {ok, Result} | {error, reason()} when SslSocket :: sslsocket(), Items :: connection_info_keys(), Result :: connection_info().
Returns the requested information items about the connection, if they are defined.
Note that client_random, server_random, master_secret and keylog are values that affect the security of connection.
In order to retrieve keylog and other secret information from a TLS 1.3
connection, keep_secrets
option must be configured in advance and
set to true
.
Note
If only undefined options are requested the resulting list can be empty.
export_key_materials(SslSocket, Labels, Contexts, WantedLengths)
View Source (since OTP 27.0)-spec export_key_materials(SslSocket, Labels, Contexts, WantedLengths) -> {ok, ExportKeyMaterials} | {error, reason()} when SslSocket :: sslsocket(), Labels :: [binary()], Contexts :: [binary() | no_context], WantedLengths :: [non_neg_integer()], ExportKeyMaterials :: [binary()].
Equivalent to
export_key_materials(TLSSocket, Labels, Contexts, WantedLengths, true).
export_key_materials(SslSocket, Labels, Contexts, WantedLengths, ConsumeSecret)
View Source (since OTP 27.0)-spec export_key_materials(SslSocket, Labels, Contexts, WantedLengths, ConsumeSecret) -> {ok, ExportKeyMaterials} | {error, exporter_master_secret_already_consumed | bad_input} when SslSocket :: sslsocket(), Labels :: [binary()], Contexts :: [binary() | no_context], WantedLengths :: [non_neg_integer()], ConsumeSecret :: boolean(), ExportKeyMaterials :: [binary()].
Uses the Pseudo-Random Function, PRF (pre TLS-1.3) or HKDF (TLS-1.3), for a TLS connection to generate and export keying materials.
In TLS-1.3 using no_context
is equivalent to specifying an empty context, that is an empty
binary, pre TLS-1.3 these will render different results. The last argument is
relevant only in TLS-1.3 and it causes the TLS-1.3 exporter_master_secret to be
consumed that is it will no longer be available, to increase security, and
further attempts to call this function will fail.
-spec filter_cipher_suites(Suites, Filters) -> Ciphers when Suites :: ciphers(), Filters :: cipher_filters(), Ciphers :: ciphers().
Removes cipher suites if any of the filter functions returns false for any part of the cipher suite.
If no filter function is supplied for some part the default behaviour regards it as if there was a filter function that returned true. For examples see Customizing cipher suites . Additionally, this function also filters the cipher suites to exclude cipher suites not supported by the cryptolib used by the OTP crypto application. That is calling ssl:filter_cipher_suites(Suites, []) will be equivalent to only applying the filters for cryptolib support.
-spec format_error(Error) -> ReasonStr when Error :: {error, reason()} | (Reason :: reason()), ReasonStr :: string().
Presents the error returned by an SSL function as a printable string, the error tag may be both included and excluded
-spec getopts(SslSocket, OptionNames) -> {ok, [gen_tcp:option()]} | {error, reason()} when SslSocket :: sslsocket(), OptionNames :: [gen_tcp:option_name()].
Gets the values of the specified socket options.
-spec getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()} when SslSocket :: sslsocket(), OptionValues :: [{inet:stat_option(), integer()}].
Equivalent to getstat/2
.
-spec getstat(SslSocket, Options) -> {ok, OptionValues} | {error, inet:posix()} when SslSocket :: sslsocket(), Options :: [inet:stat_option()], OptionValues :: [{inet:stat_option(), integer()}].
Gets one or more statistic options for the underlying TCP socket.
See inet:getstat/2 for statistic options description.
-spec negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason} when SslSocket :: sslsocket(), Protocol :: binary(), Reason :: protocol_not_negotiated | closed.
Returns the protocol negotiated through ALPN or NPN extensions.
-spec peercert(SslSocket) -> {ok, Cert} | {error, reason()} when SslSocket :: sslsocket(), Cert :: public_key:der_encoded().
The peer certificate is returned as a DER-encoded binary.
The certificate can be
decoded with public_key:pkix_decode_cert/2
Suggested further reading about
certificates is public_key User's Guide
and ssl User's Guide
-spec peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()} when SslSocket :: sslsocket(), Address :: inet:ip_address(), Port :: inet:port_number().
Returns the address and port number of the peer.
-spec prepend_cipher_suites(Preferred, Suites) -> ciphers() when Preferred :: ciphers() | cipher_filters(), Suites :: ciphers().
Make Preferred
suites become the most preferred suites.
That is put them at the head of the cipher suite list Suites
after
removing them from Suites
if present. Preferred
may be a list of
cipher suites or a list of filters in which case the filters are use
on Suites
to extract the preferred cipher list.
-spec signature_algs(Description, Version) -> signature_algs() when Description :: default | all | exclusive, Version :: protocol_version().
Lists all possible signature algorithms corresponding to Description
that are
available.
The exclusive
option will exclusively list algorithms or algorithm schemes for
that protocol version, whereas the default
and all
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 Version
.
Example:
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]
Note
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
rsa_pkcs1_sha256
instead of{sha256, rsa}
these are legacy algorithms in TLS-1.3 that apply only to certificate signatures in this version of the protocol.
-spec sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()} when SslSocket :: sslsocket(), Address :: inet:ip_address(), Port :: inet:port_number().
Returns the local address and port number of socket SslSocket
.
-spec start() -> ok | {error, reason()}.
Equivalent to start(temporary)
.
-spec start(permanent | transient | temporary) -> ok | {error, reason()}.
Starts the SSL application.
-spec stop() -> ok.
Stops the SSL application.
-spec str_to_suite(CipherSuiteName) -> erl_cipher_suite() | {error, {not_recognized, CipherSuiteName}} when CipherSuiteName :: string().
Converts an RFC or OpenSSL name string to an erl_cipher_suite/0
Returns an error if the cipher suite is not supported or the name is not a valid cipher suite name.
-spec suite_to_openssl_str(CipherSuite) -> string() when CipherSuite :: erl_cipher_suite().
Converts erl_cipher_suite/0
to OpenSSL name string.
PRE TLS-1.3 these names differ for RFC names
-spec suite_to_str(CipherSuite) -> string() when CipherSuite :: erl_cipher_suite().
Converts an erl_cipher_suite()
value to an RFC
name string.
-spec versions() -> [VersionInfo] when VersionInfo :: {ssl_app, string()} | {supported | available | implemented, [tls_version()]} | {supported_dtls | available_dtls | implemented_dtls, [dtls_version()]}.
Lists information, mainly concerning TLS/DTLS versions, in runtime for debugging and testing purposes.
app_vsn
- The application version of the SSL application.supported
- TLS versions supported with current application environment and crypto library configuration. Overridden by a version option on connect/2,3,4,listen/2
, and handshake/2,3. For the negotiated TLS version, see connection_information/1 .supported_dtls
- DTLS versions supported with current application environment and crypto library configuration. Overridden by a version option on connect/2,3,4,listen/2
, and handshake/2,3. For the negotiated DTLS version, see connection_information/1 .available
- All TLS versions supported with the linked crypto library.available_dtls
- All DTLS versions supported with the linked crypto library.implemented
- All TLS versions supported by the SSL application if linked with a crypto library with the necessary support.implemented_dtls
- All DTLS versions supported by the SSL application if linked with a crypto library with the necessary support.
Deprecated API
prf(SslSocket, Secret, Label, Seed, WantedLength)
View Source (since OTP R15B01)-spec prf(SslSocket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()} when SslSocket :: sslsocket(), Secret :: binary() | master_secret, Label :: binary(), Seed :: [binary() | prf_random()], WantedLength :: non_neg_integer().
Uses the Pseudo-Random Function (PRF) of a TLS session to generate extra key material.
It either takes user-generated values for Secret
and Seed
or atoms
directing it to use a specific value from the session security parameters.
Note
This function is replaced by
export_key_materials/4
, official documented API function since OTP 27, which is equivalent toprf(TLSSocket, master_secret, Label, [client_random, server_random, Context], WantedLength)
Other ways of calling this function was for testing purposes only and has no use case. Called in TLS-1.3 context it will now behave asexport_key_materials(TLSSocket, [Label], [Context], [WantedLength])