-type common_option() ::
          {protocol, tls | dtls} |
          {handshake, hello | full} |
          {ciphers, cipher_suites()} |
          {signature_algs, signature_algs()} |
          {signature_algs_cert, [sign_scheme()]} |
          {keep_secrets, KeepSecrets :: boolean()} |
          {max_handshake_size, HandshakeSize :: pos_integer()} |
          {versions, [protocol_version()]} |
          {log_level, Level :: logger:level() | none | all} |
          {hibernate_after, HibernateTimeout :: timeout()} |
          {receiver_spawn_opts, SpawnOpts :: [erlang:spawn_opt_option()]} |
          {sender_spawn_opts, SpawnOpts :: [erlang:spawn_opt_option()]}.

Options common to both client and server side.

• {protocol, Protocol} - Choose TLS or DTLS protocol for the transport layer security.

  Defaults to tls.

• {handshake_completion, Completion} - Possibly pause handshake at hello stage.

  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

• {keep_secrets, KeepSecrets} - 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

• {handshake_size, HandshakeSize} - Limit the acceptable handshake packet size.

  Used to limit the size of valid TLS handshake packets to avoid DoS attacks.

  Integer (24 bits unsigned). Defaults to 256*1024.

• {hibernate_after, HibernateTimeout} - Hibernate inactive connection processes

  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 not specified the process never goes into hibernation.

• {log_level, Level} - 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 Application

• {receiver|sender_spawn_opts, SpawnOpts} - Configure erlang spawn opts.

  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 common_option_cert() ::
          {certs_keys, CertsKeys :: [cert_key_conf()]} |
          {depth, AllowedCertChainLen :: pos_integer()} |
          {verify_fun, Verify :: {Verifyfun :: fun(), InitialUserState :: any()}} |
          {cert_policy_opts,
           PolicyOpts ::
               [{policy_set, [public_key:oid()]} |
                {explicit_policy, boolean()} |
                {inhibit_policy_mapping, boolean()} |
                {inhibit_any_policy, boolean()}]} |
          {crl_check, Check :: boolean() | peer | best_effort} |
          {crl_cache, crl_cache_opts()} |
          {partial_chain, anchor_fun()}.

Common certificate related options to both client and server.

• {certs_keys, CertsKeys} - At least one certificate and key pair.

  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.

• {depth, AllowedCertChainLen} - Limits the accepted number of certificates in the certificate chain.

  certificate_revoked 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. Used to mitigate DoS attack possibilities.

• {verify_fun, Verify} - Customize certificate path validation

  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

• {cert_policy_opts, PolicyOpts} - Handle certificate policies

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

• {cerl_check, Check} - Handle certificate revocation lists

  Perform CRL (Certificate Revocation List) verification (public_key:pkix_crls_validate/3) on all the certificates during the path validation (public_key:pkix_path_validation/3) of the certificate chain. Defaults to false.

• peer

  Check is only performed on the peer certificate.

• best_effort

  If certificate revocation status cannot be determined it will be accepted as valid.

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

-type common_option_dtls() ::
          {use_srtp, UseSrtp :: #{protection_profiles := [binary()], mki => binary()}}.

Common options to client and server only valid for DTLS.

• {use_srtp, UseSrtp} - Configures the use_srtp DTLS hello extension.

  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 protection_profiles and an optional mki parameters.

  protection_profiles configures the list of the client's acceptable SRTP Protection Profiles. Each profile is a 2-byte binary. Example: #{protection_profiles => [<<0,2>>, <<0,5>>]}

  mki configures the SRTP Master Key Identifier chosen by the client.

  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.

  Note

  OTP does not handle SRTP, so an external implementations of SRTP encoder/decoder and a packet demultiplexer are needed to make use of the use_srtp extension. See also transport_option option.

  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.

-type common_option_legacy() ::
          {cert, Cert :: public_key:der_encoded() | [public_key:der_encoded()]} |
          {certfile, CertPem :: file:filename()} |
          {key, Key :: key()} |
          {keyfile, KeyPem :: file:filename()} |
          {password, KeyPemPasswd :: iodata() | fun(() -> iodata())} |
          {log_alert, LogAlert :: boolean()} |
          {padding_check, PaddingCheck :: boolean()} |
          {beast_mitigation, one_n_minus_one | zero_n | disabled} |
          {ssl_imp, Imp :: new | old}.

Legacy options considered deprecated in favour of other options, insecure to use, or plainly not relevant anymore.

• {cert, Certs}

  Use option certs_keys instead.

• {certfile, CertPem}

  Use option certs_keys instead.

• {keyfile, KeyPem}

  Use option certs_keys instead.

• {password, KeyPemPasswd}

  Use option certs_keys instead.

• {log_alert, LogAlert}

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

• {padding_check, PaddingCheck} - Inter-op tradeoff option

  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, false} makes TLS vulnerable to the Poodle attack.

• {beast_mitigation, BeastMitigation} - Inter-op tradeoff option

  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.

• {ssl_imp, Imp}

  Deprecated since OTP 17, has no effect.

-type common_option_pre_tls13() ::
          {eccs, NamedCurves :: [named_curve()]} |
          {secure_renegotiate, SecureRenegotiate :: boolean()} |
          {user_lookup_fun, {Lookupfun :: fun(), UserState :: any()}}.

Options common to both client and server side pre TLS-1.3.

• {eccs, NamedCurves} - Named Elliptic Curves

  Elliptic curves that can be use in pre TLS-1.3 key exchange.

• {secure_renegotiate, SecureRenegotiate} - Inter-operate tradeoff option

  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.

• {user_lookup_fun, {LookupFun, UserState}} - PSK/SRP cipher suite 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, 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 common_option_tls13() ::
          {supported_groups, [group()]} | {key_update_at, KeyUpdateAt :: pos_integer()}.

Common options to both client and server for TLS-1.3.

• {supported_groups, Groups} - Key exchange option

  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.

• {key_update_at, KeyUpdateAt} - Session key renewal

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