-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} - Possibly pause handshake at hello stage.

  Defaults to full. If hello is specified the handshake will pause after the hello message, allowing the user to 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 client_random and various handshake secrets.

  The keep_secrets functionality is disabled (false) by default.

  Added in OTP 23.2.

• {max_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, the 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 connections using Erlang distribution, the 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()}]} |
          {allow_any_ca_purpose, Allow :: 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 can 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.

  The different signature algorithms are prioritized in the following order: eddsa, ecdsa, rsa_pss_pss, rsa, and dsa. If more than one key is supplied for the same signature algorithm, they will be prioritized by strength (except for engine keys; see the next paragraph). 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; thus, alternatives should be chosen for good reasons.

  Engine keys will be favored over other keys. As engine keys cannot be inspected, supplying more than one engine key makes no sense.

  When this option is specified it overrides all single certificate and key options. For examples, see the User's Guide.

  Note

  eddsa certificates are only supported by TLS-1.3 implementations that do 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 do not support rsa_pss_pss.

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

  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 X.509-path validation when an error occurs 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 regardless of verification failures, and the connection is established.
  • If called with an extension unknown to the user application, the fun is to return {unknown, UserState}.

  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 in the 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 (the 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.

  • {invalid_ext_keyusage, [public_key:oid()]}

  If the peer certificate specifies the extended keyusage extension and does not include the purpose for either being a TLS server (id-kp-ServerAuth) or TLS client (id-kp-ClientAuth) depending on the peers role.

  • {ca_invalid_ext_keyusage, [public_key:oid()]}

  If a CA certificate specifies the extended keyusage extension and does not include the purpose for either being a TLS server (id-kp-ServerAuth) or TLS client (id-kp-ClientAuth) depending on the role of the peer chained with this CA, or the option allow_any_ca_purpose is set to true but the special any-value (anyExtendedKeyUsage) is not included in the CA cert purposes.

  • PKIX X-509-path validation error

    For possible reasons, see public_key:pkix_path_validation/3.

• {cert_policy_opts, PolicyOpts} - Handle certificate policies.

  Configure X.509 certificate policy handling for the certificate path validation process; see public_key:pkix_path_validation/3 for more details.

• {allow_any_ca_purpose, boolean()} - Handle certificate extended key usages extension

  If a CA certificate has an extended key usage extension but it does not want to restrict the usages of the key it can include a special anyExtendedKeyUsage purpose. If this is option is set to true all key usage purposes is automatically accepted for a CA that include that purpose, the options default to false.

• {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. Check defaults to false.

  The meaning of Check is as follows:

  • false

    No checks are performed.

  • 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 parameter and an optional mki parameter.

  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 option transport_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 favor 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 LogAlert is false, TLS/DTLS Alert reports are not displayed. Deprecated in OTP 22; use {log_level, Level} instead.

• {padding_check, PaddingCheck} - Inter-op trade-off 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 trade-off 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 client and server side prior to TLS-1.3.

• {eccs, NamedCurves} - Named Elliptic Curves

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

• {secure_renegotiate, SecureRenegotiate} - Inter-operate trade-off option

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

• {user_lookup_fun, {LookupFun, UserState}} - PSK/SRP cipher suite option

  The lookup fun is to be 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 the hint presented by the server or 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, which 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 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.