This module contains interface functions for the TLS/DTLS protocol.
For detailed information about the supported standards see
An opaque reference to the TLS/DTLS connection, may be used for equality matching.
The default socket options are
For valid options, see the
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 as described above.
The
Defaults to
Choose TLS or DTLS protocol for the transport layer security.
Defaults to
Defaults to
The DER-encoded user certificate. Note that the cert option may also
be a list of DER-encoded certificates where the first one is the user
certificate, and the rest of the certificates constitutes the
certificate chain. 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
Path to a file containing the user certificate on PEM format or possible several
certificates where the first one is the user certificate and the rest of the certificates
constitutes the certificate chain. For more details see
The DER-encoded user's private key or a map referring to a crypto
engine and its key reference that optionally can be password protected,
see also
Path to the file containing the user's
private PEM-encoded key. As PEM-files can contain several
entries, this option defaults to the same file as given by
option
String containing the user's password or a function returning same type. Only used if the private keyfile is password-protected.
A list of a certificate (or possible a certificate and its
chain) and the associated key of the certificate, that may be
used to authenticate the client or the server. The
certificate key pair that is considered best and matches
negotiated parameters for the connection will be selected.
Different signature algorithms are prioritized in the order
A certificate (or possibly a certificate and its chain) 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.
A list of cipher suites that should be supported
The function
If you compose your own
Note that TLS-1.3 and TLS-1.2 cipher suites are not overlapping sets of cipher suites so 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.
Explicitly list acceptable signature algorithms for certificates and handshake messages
in the preferred order. The client will send its list as the client hello
In TLS-1.2 a somewhat more explicit negotiation is made possible using a list of
{
In TLS-1.3 these algorithm pairs are
replaced by so called signature schemes
Signature algorithms used for certificates may be overridden by the
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
[
%% 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_pss_sha512,
rsa_pss_pss_sha384,
rsa_pss_pss_sha256,
rsa_pss_rsae_sha512,
rsa_pss_rsae_sha384,
rsa_pss_rsae_sha256]
[
%% 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}
]
[
%% 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.
TLS-1.2 algorithms will not be negotiated for TLS-1.3, but TLS-1.3 RSASSA-PSS
Explicitly list acceptable signature schemes (algorithms)
in the preferred order. Overrides the algorithms supplied in
In addition to the
The client will send a
Note that supported signature schemes for TLS-1.2
are
TLS 1.3 introduces the "supported_groups" extension that is used for negotiating the Diffie-Hellman parameters in a TLS 1.3 handshake. Both client and server can specify a list of parameters that they are willing to use.
If it is not specified it will use a default list ([x25519, x448, secp256r1, secp384r1]) that is filtered based on the installed crypto library version.
Specifies if to reject renegotiation attempt that does
not live up to
Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path. So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 10.
The verification fun is to be defined as follows:
fun(OtpCert :: #'OTPCertificate'{},
Event, InitialUserState :: term()) ->
{valid, UserState :: term()} |
{fail, Reason :: term()} | {unknown, UserState :: term()}.
fun(OtpCert :: #'OTPCertificate'{}, DerCert :: public_key:der_encoded(),
Event, InitialUserState :: term()) ->
{valid, UserState :: term()} |
{fail, Reason :: term()} | {unknown, UserState :: term()}.
Types:
Event = {bad_cert, Reason :: atom() |
{revoked, atom()}} |
{extension, #'Extension'{}} |
valid |
valid_peer
The verification fun is called during the X509-path
validation when an error or an extension unknown to the SSL
application is encountered. It is also called when a
certificate is considered valid by the path validation to
allow access to each certificate in the path to the user
application. It differentiates between the peer certificate
and the CA certificates by using
If the verify callback fun returns
If the verify callback fun returns
If the verify callback fun always returns
If called with an extension unknown to the user application,
return value
Note that if the fun returns
Default option
{fun(_,{bad_cert, _} = Reason, _) ->
{fail, Reason};
(_,{extension, _}, UserState) ->
{unknown, UserState};
(_, valid, UserState) ->
{valid, UserState};
(_, valid_peer, UserState) ->
{valid, UserState}
end, []}
Default option
{fun(_,{bad_cert, _}, UserState) ->
{valid, UserState};
(_,{extension, #'Extension'{critical = true}}, UserState) ->
{valid, UserState};
(_,{extension, _}, UserState) ->
{unknown, UserState};
(_, valid, UserState) ->
{valid, UserState};
(_, valid_peer, UserState) ->
{valid, UserState}
end, []}
The possible path validation errors are given on form
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
intermediate CA (trusted anchor does not have to be
self-signed according to X-509) by using option
The chain consisted only of one self-signed certificate.
For possible reasons, see
Perform CRL (Certificate Revocation List) verification
The CA certificates specified for the connection will be used to construct the certificate chain validating the CRLs.
The CRLs will be fetched from a local or external cache. See
Specify how to perform lookup and caching of certificate revocation lists.
There are two implementations available:
This module maintains a cache of CRLs. CRLs can be
added to the cache using the function
Enables fetching of CRLs specified as http URIs in
This 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
For a given hash value, this module finds all
consecutive
The following argument is required:
Specifies the directory in which the CRLs can be found.
fun(Chain::[public_key:der_encoded()]) ->
{trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca.
Claim an intermediate CA in the chain as trusted. TLS then
performs
TLS protocol versions supported by started clients and servers.
This option overrides the application environment option
The lookup fun is to defined as follows:
fun(psk, PSKIdentity :: binary(), UserState :: term()) ->
{ok, SharedSecret :: binary()} | error;
fun(srp, Username :: binary(), UserState :: term()) ->
{ok, {SRPParams :: srp_param_type(), Salt :: binary(),
DerivedKey :: binary()}} | error.
For Pre-Shared Key (PSK) cipher suites, the lookup fun is
called by the client and server to determine the shared
secret. When called by the client,
For Secure Remote Password (SRP), the fun is only used by the server to
obtain parameters that it uses to generate its session keys.
Identifies a TLS session.
If set to
Specifies the log level for a TLS/DTLS
connection. Alerts are logged on
When an integer-value is specified,
Integer (24 bits unsigned). Used to limit the size of valid TLS handshake packets to avoid DoS attacks. Defaults to 256*1024.
Affects TLS-1.0 connections only.
If set to
Using
Affects TLS-1.0 connections only. Used to change the BEAST
mitigation strategy to interoperate with legacy software.
Defaults to
Using
Deprecated since OTP-17, has no effect.
Configures the session ticket functionality in TLS 1.3 client and server.
Configures the maximum amount of bytes that can be sent on a TLS 1.3 connection before an automatic key update is performed.
There are cryptographic limits on the amount of plaintext which can be safely
encrypted under a given set of keys. The current default ensures that data integrity
will not be breached with probability greater than 1/2^57. For more information see
The default value of this option shall provide the above mentioned security guarantees and it shall be reasonable for most applications (~353 TB).
Configures the middlebox compatibility mode on a TLS 1.3 connection.
A significant number of middleboxes misbehave when a TLS 1.3 connection is negotiated. Implementations can increase the chance of making connections through those middleboxes by making the TLS 1.3 handshake more like a TLS 1.2 handshake.
The middlebox compatibility mode is enabled (
Configures spawn options of TLS sender and receiver processes.
Setting up garbage collection options can be helpful for trade-offs between
CPU usage and Memory usage.
See
For dist connections, default sender option is
Configures a TLS 1.3 connection for keylogging
In order to retrieve keylog information on a TLS 1.3 connection, it must be configured in advance to keep the client_random and various handshake secrets.
The keep_secrets functionality is disabled (
Added in OTP 23.2
Defaults to
Reuses a specific session. The session should be referred by its session id if it is
earlier saved with the option
When
If set to true, sends the certificate authorities extension in TLS-1.3 client hello. The default is false. Note that setting it to true may result in a big overhead if you have many trusted CA certificates. Since OTP-24.3.
The DER-encoded trusted certificates. If this option
is supplied it overrides option
Path to a file containing PEM-encoded CA certificates. The CA certificates are used during server authentication and when building the client certificate chain.
When PEM caching is enabled, files provided with
this option will be checked for updates at fixed time intervals specified by the
Alternatively, CA certificates can be provided as a DER-encoded
binary with
The list of protocols supported by the client to be sent to the server to be used for an Application-Layer Protocol Negotiation (ALPN). If the server supports ALPN then it will choose a protocol from this list; otherwise it will fail the connection with a "no_application_protocol" alert. A server that does not support ALPN will ignore this value.
The list of protocols must not contain an empty binary.
The negotiated protocol can be retrieved using the
Indicates that the client is to try to perform Next Protocol Negotiation.
If precedence is server, the negotiated protocol is the first protocol to be shown on the server advertised list, which is also on the client preference list.
If precedence is client, the negotiated protocol is the first protocol to be shown on the client preference list, which is also on the server advertised list.
If the client does not support any of the server advertised protocols or the server does not advertise any protocols, the client falls back to the first protocol in its list or to the default protocol (if a default is supplied). If the server does not support Next Protocol Negotiation, the connection terminates if no default protocol is supplied.
Specifies the maximum fragment length the client
is prepared to accept from the server.
See
Specifies the identity the client presents to the server.
The matching secret is found by calling
Specifies the username and password to use to authenticate to the server.
Specify the hostname to be used in TLS Server Name Indication extension.
If not specified it will default to the
The
The special value
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 example the get standard HTTPS handling
provide the already implememnted fun from the public_key application for HTTPS.
Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired TLS version downgrade. Defaults to false
Note this option is not needed in normal TLS usage and should not be used to implement new clients. But legacy clients that retries connections in the following manner
may use it to avoid undesired TLS version downgrade. Note that TLS_FALLBACK_SCSV must also be supported by the server for the prevention to work.
Configures the session ticket functionality. Allowed values are
where
If it is set to
This option is supported by TLS 1.3 and above. See also
Configures the session tickets to be used for session resumption. It is a mandatory
option in
Session tickets are only sent to user if option session_tickets is set
to
This option is supported by TLS 1.3 and above. See also
Configures the early data to be sent by the client.
In order to be able to verify that the server has the intention to process the early data, the following 3-tuple is sent to the user process:
where
It is the responsibility of the user to handle a rejected Early Data and to resend when it is appropriate.
Configures the
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.
The value is a map with a mandatory
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.
This extension MUST only be used with DTLS, and not with TLS.
OTP does not handle SRTP, so an external implementations of SRTP
encoder/decoder and a packet demultiplexer are needed to make use
of the
The DER-encoded trusted certificates. If this option
is supplied it overrides option
Determines if a TLS-1.3 server should include the authorities
extension in its certificate request message that will be sent if the
option
A reason to exclude the extension would be if the server wants to communicate with clients incapable of sending complete certificate chains that adhere to the extension, but the server still has the capability to recreate a chain that it can verify.
Path to a file containing PEM-encoded CA certificates. The CA certificates are used to build the server certificate chain and for client authentication. The CAs are also used in the list of acceptable client CAs passed to the client when a certificate is requested. Can be omitted if there is no need to verify the client and if there are no intermediate CAs for the server certificate.
When PEM caching is enabled, files provided with
this option will be checked for updates at fixed time intervals specified by the
Alternatively, CA certificates can be provided as a DER-encoded
binary with
The DER-encoded Diffie-Hellman parameters. If
specified, it overrides option
The
Path to a file containing PEM-encoded Diffie Hellman parameters to be used by the server if a cipher suite using Diffie Hellman key exchange is negotiated. If not specified, default parameters are used.
The
Client certificates are an optional part of the TLS protocol.
A server only does x509-certificate path validation in mode
Used together with
The boolean value true specifies that the server will
agree to reuse sessions. Setting it to false will result in an empty
session table, that is no sessions will be reused.
See also option
Enables the TLS/DTLS server to have a local policy
for deciding if a session is to be reused or not. Meaningful
only if
Indicates the server will try to perform Application-Layer Protocol Negotiation (ALPN).
The list of protocols is in order of preference. The protocol negotiated will be the first in the list that matches one of the protocols advertised by the client. If no protocol matches, the server will fail the connection with a "no_application_protocol" alert.
The negotiated protocol can be retrieved using the
List of protocols to send to the client if the client
indicates that it supports the Next Protocol extension. The
client can select a protocol that is not on this list. The
list of protocols must not contain an empty binary. If the
server negotiates a Next Protocol, it can be accessed using
the
Specifies the server identity hint, which the server presents to the client.
If set to
If the server receives a SNI (Server Name Indication) from the client
matching a host listed in the
If the server receives a SNI (Server Name Indication)
from the client, the given function will be called to
retrieve
In protocols that support client-initiated
renegotiation, the cost 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 strictly disabled by
setting this option to
If true, use the server's preference for cipher selection. If false (the default), use the client's preference.
If true, use the server's preference for ECC curve selection. If false (the default), use the client's preference.
Configures the session ticket functionality. Allowed values are
If it is not set to
Pre-shared key session ticket resumption does not include any certificate exchange,
hence the function
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.
If it is set to
This option is supported by TLS 1.3 and above. See also
Configures the seed used for the encryption of stateless session tickets.
Allowed values are any randomly generated
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.
Inaccurate time synchronization between server instances can also affect session ticket freshness checks, potentially causing false negatives as well as false positives.
This option is supported by TLS 1.3 and above and only with stateless session tickets.
Configures the server's built-in anti replay feature based on Bloom filters.
Allowed values are the pre-defined
This option is supported by TLS 1.3 and above and only with stateless session tickets.
Ticket lifetime, the number of tickets sent by the server and the maximum number of tickets
stored by the server in stateful mode are configured by
If
The cookie extension has two main purposes. It allows the server to force the client to demonstrate reachability at their apparent network address (thus providing a measure of DoS protection). This is primarily useful for non-connection-oriented transports. It also allows to offload the server's state to the client. The cookie extension is enabled by default as it is a mandatory extension in RFC8446.
Configures if the server accepts (
This option is a placeholder, early data is not yet implemented on the server side.
Configures the
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.
The value is a map with a mandatory
Upon receipt of a "use_srtp" extension containing a "srtp_mki" field, the server MUST either (assuming it accepts the extension at all):
include a matching "srtp_mki" value in its "use_srtp" extension to indicate that it will make use of the MKI, or
return an empty "srtp_mki" value to indicate that it cannot make use of the MKI (default).
This extension MUST only be used with DTLS, and not with TLS.
OTP does not handle SRTP, so an external implementations of SRTP
encoder/decoder and a packet demultiplexer are needed to make use
of the
Make
Lists all possible cipher suites corresponding to
TLS-1.3 has no overlapping cipher suites with previous
TLS versions, that is the result of
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
Same as
Returns a list of supported ECCs.
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.
Upgrades a
If the option
If the option
If the option
Opens a TLS/DTLS connection to
When the option
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
If the option
Closes a TLS/DTLS connection.
Closes or downgrades a TLS connection. In the latter case the transport
connection will be handed over to the
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.
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.
Returns the most relevant information about the connection, ssl options that are undefined will be filtered out. Note that values that affect the security of the connection will only be returned if explicitly requested by connection_information/2.
The legacy
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. Meaningful atoms, not specified above, are the ssl option names.
In order to retrieve keylog and other secret information from a TLS 1.3
connection,
If only undefined options are requested the resulting list can be empty.
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
Presents the error returned by an SSL function as a printable string.
Gets the values of the specified socket options.
Gets one or more statistic options for the underlying TCP socket.
See inet:getstat/2 for statistic options description.
Performs the TLS/DTLS server-side handshake.
Returns a new TLS/DTLS socket if the handshake is successful.
If the option
Not setting the timeout makes the server more vulnerable to DoS attacks.
If
The ordinary
If
Not setting the timeout makes the server more vulnerable to DoS attacks.
If option
If the option
Cancel the handshake with a fatal
Continue the TLS handshake, possibly with new, additional or changed options.
Creates an SSL listen socket.
Returns the protocol negotiated through ALPN or NPN extensions.
The peer certificate is returned as a DER-encoded binary.
The certificate can be decoded with
Returns the address and port number of the peer.
Make
Uses the Pseudo-Random Function (PRF) of a TLS session to generate
extra key material. It either takes user-generated values for
Receives a packet from a socket in passive
mode. A closed socket is indicated by return value
Argument
Optional argument
Initiates a new handshake. A notable return value is
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
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
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.
Writes
A notable return value is
Sets options according to
Immediately closes a socket in one or two directions.
To be able to handle that the peer has done a shutdown on
the write side, option
Lists all possible signature algorithms corresponding to
Example:
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
Returns the local address and port number of socket
Starts the SSL application. Default type
is
Stops the SSL application.
Converts an RFC or OpenSSL name string to an
Converts
PRE TLS-1.3 these names differ for RFC names
Converts
Accepts an incoming connection request on a listen socket.
Most API functions require that the TLS/DTLS connection is established to work as expected.
The accepted socket inherits the options set for
The default
value for
Lists information, mainly concerning TLS/DTLS versions, in runtime for debugging and testing purposes.