-type allowed_cert_chain_length() :: integer().

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.

-type beast_mitigation() :: one_n_minus_one | zero_n | disabled.

Affects TLS-1.0 connections only. Used to change the BEAST mitigation strategy to interoperate with legacy software. Defaults to one_n_minus_one.

one_n_minus_one - Perform 1/n-1 BEAST mitigation.

zero_n - Perform 0/n BEAST mitigation.

disabled - Disable BEAST mitigation.

Warning

Using {beast_mitigation, disabled} makes TLS-1.0 vulnerable to the BEAST attack.

-type cert() :: public_key:der_encoded().

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 client_cacerts/0, server_cacerts/0, or client_cafile/0, server_cafile/0 are used to construct the chain. If this option is supplied, it overrides option certfile.

-type cert_key_conf() ::
    #{cert => cert(),
      key => key(),
      certfile => cert_pem(),
      keyfile => key_pem(),
      password => key_pem_password()}.

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.

-type cert_pem() :: file:filename().

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 cert/0,

-type certs_keys() :: [cert_key_conf()].

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 eddsa, ecdsa, rsa_pss_pss, rsa and dsa. If more than one key is supplied for the same signing algorithm (which is probably an unusual use case) they will prioritized by strength unless it is a so called engine key that will be favoured over other keys. As engine keys cannot be inspected, supplying more than one engine key will make no sense. This offers flexibility to for instance configure a newer certificate that is expected to be used in most cases and an older but acceptable certificate that will only be used to communicate with legacy systems. Note that there is a trade off between the induced overhead and the flexibility so alternatives should be chosen for good reasons. If the certs_keys option is specified it overrides all single certificate and key options. For examples see the Users Guide

Note

eddsa certificates are only supported by TLS-1.3 that does not support dsa certificates. rsa_pss_pss (RSA certificates using Probabilistic Signature Scheme) are supported in TLS-1.2 and TLS-1.3, but some TLS-1.2 implementations may not support rsa_pss_pss.

-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 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.

-type crl_cache_opts() :: {Module :: atom(), {DbHandle :: internal | term(), Args :: list()}}.

Specify how to perform lookup and caching of certificate revocation lists. Module defaults to ssl_crl_cache with DbHandlebeing internal and an empty argument list.

There are two implementations available:

• ssl_crl_cache - This 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 - 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 .rN, where N 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 utility c_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 whose nextUpdate 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 crl_check() :: boolean() | peer | best_effort.

Configure X509 certificate policy handling for the certificate path validation process see (public_key:pkix_path_validation/3) for further explanation.

-type custom_user_lookup() :: {Lookupfun :: fun(), UserState :: any()}.

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, PSKIdentity is set to the hint presented by the server or to undefined. When called by the server, PSKIdentity is the identity presented 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. DerivedKey is to be derived according to RFC 2945 and RFC 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Password])])

-type custom_verify() :: {Verifyfun :: fun(), InitialUserState :: any()}.

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 valid_peer or valid as Event argument to the verification fun. See the public_key User's Guide for definition of #'OTPCertificate'{} and #'Extension'{}.

• If the verify callback fun returns {fail, Reason}, the verification process is immediately stopped, an alert is sent to the peer, and the TLS/DTLS handshake terminates.

• If the verify callback fun returns {valid, UserState}, the verification process continues.

• If the verify callback fun always returns {valid, UserState}, the TLS/DTLS handshake does not terminate regarding verification failures and the connection is established.

• If called with an extension unknown to the user application, return value {unknown, UserState} is to be used.

  Note that if the fun returns unknown for an extension marked as critical, validation will fail.

Default option verify_fun in verify_peer mode:

{fun(_,{bad_cert, _} = Reason, _) ->
	 {fail, Reason};
    (_,{extension, _}, UserState) ->
	 {unknown, UserState};
    (_, valid, UserState) ->
	 {valid, UserState};
    (_, valid_peer, UserState) ->
         {valid, UserState}
 end, []}

Default option verify_fun in mode verify_none:

{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 {bad_cert, Reason} where Reason is:

• unknown_ca - 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 partial_chain.

• selfsigned_peer - The chain consisted only of one self-signed certificate.

• PKIX X-509-path validation error - For possible reasons, see public_key:pkix_path_validation/3

-type handshake_completion() :: hello | full.

Defaults to full. If hello is specified the handshake will pause after the hello message and give the user a possibility make decisions based on hello extensions before continuing or aborting the handshake by calling handshake_continue/3 or handshake_cancel/1

-type handshake_size() :: integer().

Integer (24 bits unsigned). Used to limit the size of valid TLS handshake packets to avoid DoS attacks. Defaults to 256*1024.

-type hibernate_after() :: timeout().

When an integer-value is specified, TLS/DTLS-connection goes into hibernation after the specified number of milliseconds of inactivity, thus reducing its memory footprint. When undefined is specified (this is the default), the process never goes into hibernation.

-type keep_secrets() :: boolean().

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 (false) by default.

Added in OTP 23.2

-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.

If this option is supplied, it overrides option keyfile.

-type key_pem() :: file:filename().

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 certfile.

-type key_pem_password() :: iodata() | fun(() -> iodata()).

String containing the user's password or a function returning same type. Only used if the private keyfile is password-protected.

-type key_update_at() :: pos_integer().

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 Limits on Authenticated Encryption Use in TLS.

Warning

The default value of this option shall provide the above mentioned security guarantees and it shall be reasonable for most applications (~353 TB).

-type log_alert() :: boolean().

If set to false, TLS/DTLS Alert reports are not displayed. Deprecated in OTP 22, use {log_level, logging_level/0} instead.

-type logging_level() :: logger:level() | none | all.

Specifies the log level for a TLS/DTLS connection. Alerts are logged on notice level, which is the default level. The level debug triggers verbose logging of TLS/DTLS protocol messages. See also ssl(6)

-type middlebox_comp_mode() :: boolean().

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 (true) by default.

-type padding_check() :: boolean().

Affects TLS-1.0 connections only. If set to false, it disables the block cipher padding check to be able to interoperate with legacy software.

Warning

Using {padding_check, boolean()} makes TLS vulnerable to the Poodle attack.

-type protocol() :: tls | dtls.

Choose TLS or DTLS protocol for the transport layer security. Defaults to tls. For DTLS other transports than UDP are not yet supported.

-type protocol_versions() :: [protocol_version()].

TLS protocol versions supported by started clients and servers. This option overrides the application environment option protocol_version and dtls_protocol_version. If the environment option is not set, it defaults to all versions, supported by the SSL application. See also ssl(6).

-type root_fun() :: fun().

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 public_key:pkix_path_validation/3 with the selected CA as trusted anchor and the rest of the chain.

-type secure_renegotiation() :: boolean().

Specifies if to reject renegotiation attempt that does not live up to RFC 5746. By default secure_renegotiate is set to true, that is, secure renegotiation is enforced. If set to false secure renegotiation will still be used if possible, but it falls back to insecure renegotiation if the peer does not support RFC 5746.

-type session_id() :: binary().

Identifies a TLS session.

-type session_tickets() :: client_session_tickets() | server_session_tickets().

Configures the session ticket functionality in TLS 1.3 client and server.

-type sign_schemes() :: [sign_scheme()].

Explicitly list acceptable signature schemes (algorithms) 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.

Note

Note that supported signature schemes for TLS-1.2 are sign_scheme_legacy/0 and rsassa_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()} 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 (algorithms) 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 spawn_opts() :: [erlang:spawn_opt_option()].

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 erlang:spawn_opt/2.

For dist connections, default sender option is [...{priority, max}], this priority option cannot be changed. For all connections, ...link is added to receiver and cannot be changed.

-type ssl_imp() :: new | old.

Deprecated since OTP 17, has no effect.

-type supported_groups() :: [group()].

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.