-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()]}.

客户端和服务器端通用的选项。

• {protocol, Protocol} - 为传输层安全性选择 TLS 或 DTLS 协议。

  默认为 tls。

• {handshake, Completion} - 可能在 hello 阶段暂停握手。

  默认为 full。如果指定 hello，则握手将在 hello 消息后暂停，允许用户在继续或中止握手之前基于 hello 扩展做出决策，方法是调用 handshake_continue/3 或 handshake_cancel/1。

• {keep_secrets, KeepSecrets} - 配置 TLS 1.3 连接以进行密钥记录。

  为了检索 TLS 1.3 连接上的密钥日志信息，必须预先配置为保留 client_random 和各种握手密钥。

  keep_secrets 功能默认情况下禁用 (false)。

  在 OTP 23.2 中添加。

• {max_handshake_size, HandshakeSize} - 限制可接受的握手数据包大小。

  用于限制有效 TLS 握手数据包的大小，以避免 DoS 攻击。

  整数（24 位，无符号）。默认为 256*1024。

• {hibernate_after, HibernateTimeout} - 休眠不活动的连接进程。

  当指定整数值时，TLS/DTLS 连接在指定的非活动毫秒数后进入休眠状态，从而减少其内存占用。如果未指定，则进程永远不会进入休眠状态。

• {log_level, Level} - 指定 TLS/DTLS 连接的日志级别。

  警报记录在 notice 级别，这是默认级别。debug 级别触发 TLS/DTLS 协议消息的详细日志记录。另请参阅 SSL 应用程序

• {receiver|sender_spawn_opts, SpawnOpts} - 配置 erlang spawn opts。

  配置 TLS 发送方和接收方进程的 spawn 选项。

  设置垃圾回收选项有助于在 CPU 使用率和内存使用率之间进行权衡。请参阅 erlang:spawn_opt/2。

  对于使用 Erlang 分布的连接，默认发送方选项为 [...{priority, max}]；此优先级选项无法更改。对于所有连接，...link 将添加到接收方，并且无法更改。

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

客户端和服务器通用的与证书相关的选项。

• {certs_keys, CertsKeys} - 至少一个证书和密钥对。

  一个证书列表（或者可能是证书及其链）以及可用于验证客户端或服务器的证书的相关密钥。将选择被认为最佳且与连接的协商参数匹配的证书密钥对。

  不同的签名算法按以下顺序排列优先级：eddsa、ecdsa、rsa_pss_pss、rsa 和 dsa。如果为同一签名算法提供了多个密钥，则将按强度排列优先级（*引擎密钥*除外；请参阅下一段）。这提供了灵活性，例如，配置一个预计在大多数情况下使用的新证书，以及一个较旧但可接受的证书，该证书仅用于与旧系统通信。请注意，诱导开销和灵活性之间存在权衡；因此，应该出于充分的理由选择替代方案。

  引擎密钥将优先于其他密钥。由于无法检查引擎密钥，因此提供多个引擎密钥毫无意义。

  指定此选项后，它将覆盖所有单个证书和密钥选项。有关示例，请参见用户指南。

  注意

  eddsa 证书仅受不支持 dsa 证书的 TLS-1.3 实现支持。rsa_pss_pss（使用概率签名方案的 RSA 证书）在 TLS-1.2 和 TLS-1.3 中受支持，但某些 TLS-1.2 实现不支持 rsa_pss_pss。

• {depth, AllowedCertChainLen} - 限制证书链中允许的证书数量。

  在有效的证书路径中，对等证书之后可以跟的最大非自颁发中间证书数量。因此，如果深度为 0，则对等方必须由受信任的 ROOT-CA 直接签名；如果深度为 1，则路径可以是 PEER、CA、ROOT-CA；如果深度为 2，则路径可以是 PEER、CA、CA、ROOT-CA，依此类推。默认值为 10。用于缓解 DoS 攻击的可能性。

• {verify_fun, Verify} - 自定义证书路径验证

  验证函数定义如下

  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

  当发生错误或遇到 SSL 应用程序未知的扩展时，在 X.509 路径验证期间调用验证函数。当路径验证认为证书有效时，也会调用它以允许用户应用程序访问路径中的每个证书。它通过使用 valid_peer 或 valid 作为验证函数的 Event 参数来区分对等证书和 CA 证书。有关 #'OTPCertificate'{} 和 #'Extension'{} 的定义，请参阅Public_Key 用户指南。

  • 如果验证回调函数返回 {fail, Reason}，则验证过程将立即停止，向对等方发送警报，并且 TLS/DTLS 握手终止。
  • 如果验证回调函数返回 {valid, UserState}，则验证过程继续。
  • 如果验证回调函数始终返回 {valid, UserState}，则无论验证失败如何，TLS/DTLS 握手都不会终止，并且将建立连接。
  • 如果调用了用户应用程序未知的扩展，则该函数应返回 {unknown, UserState}。

  请注意，如果某个扩展被标记为关键扩展，而该函数返回 unknown，则验证将失败。

  verify_peer 模式下的默认选项 verify_fun

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

  模式 verify_none 中的默认选项 verify_fun

   {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, []}

  可能的路径验证错误以 {bad_cert, Reason} 的形式给出，其中 Reason 为

  • unknown_ca

    在受信任的存储中未找到受信任的 CA。受信任的 CA 通常是所谓的 ROOT CA，它是一个自签名证书。可以通过使用选项 partial_chain 为中间 CA（根据 X-509，受信任的锚点不必是自签名的）声明信任。

  • selfsigned_peer

    该链仅由一个自签名证书组成。

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

  如果对等证书指定了扩展密钥用法扩展，并且未包含作为 TLS 服务器（id-kp-ServerAuth）或 TLS 客户端（id-kp-ClientAuth）的目的，具体取决于对等方的角色。

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

  如果 CA 证书指定了扩展密钥用法扩展，并且未包含作为 TLS 服务器（id-kp-ServerAuth）或 TLS 客户端（id-kp-ClientAuth）的目的，具体取决于与此 CA 链接的对等方的角色，或者选项 allow_any_ca_purpose 设置为 true，但 CA 证书目的中不包含特殊值 (anyExtendedKeyUsage)。

  • PKIX X-509 路径验证错误

    有关可能的原因，请参阅 public_key:pkix_path_validation/3。

• {cert_policy_opts, PolicyOpts} - 处理证书策略。

  配置证书路径验证过程的 X.509 证书策略处理；有关更多详细信息，请参阅 public_key:pkix_path_validation/3。

• {allow_any_ca_purpose, boolean()} - 处理证书扩展密钥用法扩展

  如果 CA 证书具有扩展密钥用法扩展，但不希望限制密钥的用法，则可以包含一个特殊的 anyExtendedKeyUsage 目的。如果此选项设置为 true，则会自动接受包含该目的的 CA 的所有密钥用法目的，该选项默认为 false。

• {cerl_check, Check} - 处理证书吊销列表。

  在证书链的路径验证 (public_key:pkix_path_validation/3) 期间，对所有证书执行 CRL（证书吊销列表）验证 (public_key:pkix_crls_validate/3)。Check 默认为 false。

  Check 的含义如下

  • false

    不执行任何检查。

  • peer

    仅对对等证书执行检查。

  • best_effort

    如果无法确定证书吊销状态，则会将其接受为有效。

    为连接指定的 CA 证书将用于构建验证 CRL 的证书链。

    CRL 将从本地或外部缓存中获取。请参阅 ssl_crl_cache_api。

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

仅对 DTLS 有效的客户端和服务器通用选项。

• {use_srtp, UseSrtp} - 配置 use_srtp DTLS hello 扩展。

  为了协商使用 SRTP 数据保护，客户端在 DTLS 扩展客户端 hello 中包含一个类型为“use_srtp”的扩展。仅当传输的数据是 RTP 或 RTCP 时，才必须使用此扩展。

  该值是一个映射，其中包含强制性 protection_profiles 参数和一个可选的 mki 参数。

  protection_profiles 配置客户端可接受的 SRTP 保护配置文件列表。每个配置文件都是一个 2 字节的二进制文件。示例：#{protection_profiles => [<<0,2>>, <<0,5>>]}

  mki 配置客户端选择的 SRTP 主密钥标识符。

  srtp_mki 字段包含与由此握手派生的 SRTP 主密钥关联的 SRTP MKI 的值。每个 SRTP 会话在任何给定时间都必须只有一个主密钥，该主密钥用于保护数据包。客户端必须选择 MKI 值，使其与上次使用的 MKI 值不同，并且应使这些值在 TLS 会话期间保持唯一。

  注意

  OTP 不处理 SRTP，因此需要 SRTP 编码器/解码器和数据包多路分解器的外部实现才能使用 use_srtp 扩展。另请参阅选项 transport_option。

  收到包含“use_srtp”扩展的扩展 hello 的服务器可以通过在扩展服务器 hello 中包含一个类型为“use_srtp”的扩展（带有选择的保护配置文件）来同意使用 SRTP。仅当传输的数据是 RTP 或 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}.

旧版选项，被认为已弃用而倾向于其他选项，使用不安全，或者根本不再相关。

• {cert, Certs}

  请改用选项 certs_keys。

• {certfile, CertPem}

  请改用选项 certs_keys。

• {keyfile, KeyPem}

  请改用选项 certs_keys。

• {password, KeyPemPasswd}

  请改用选项 certs_keys。

• {log_alert, LogAlert}

  如果 LogAlert 为 false，则不会显示 TLS/DTLS 警报报告。在 OTP 22 中已弃用；请改用 {log_level, Level}。

• {padding_check, PaddingCheck} - 互操作权衡选项

  仅影响 TLS-1.0 连接。如果设置为 false，它将禁用块密码填充检查，以便能够与旧软件互操作。

  警告

  使用 {padding_check, false} 会使 TLS 容易受到 Poodle 攻击。

• {beast_mitigation, BeastMitigation} - 互操作权衡选项

  仅影响 TLS-1.0 连接。用于更改 BEAST 缓解策略以与旧软件互操作。默认为 one_n_minus_one。

  one_n_minus_one - 执行 1/n-1 BEAST 缓解。

  zero_n - 执行 0/n BEAST 缓解。

  disabled - 禁用 BEAST 缓解。

  警告

  使用 {beast_mitigation, disabled} 会使 TLS-1.0 容易受到 BEAST 攻击。

• {ssl_imp, Imp}

  自 OTP 17 起已弃用；无效。

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

TLS-1.3 之前客户端和服务器端通用的选项。

• {eccs, NamedCurves} - 命名椭圆曲线

  可以在 TLS-1.3 之前的密钥交换中使用的椭圆曲线。

• {secure_renegotiate, SecureRenegotiate} - 互操作权衡选项

  指定是否拒绝不符合 RFC 5746 的重新协商尝试。默认情况下，SecureRenegotiate 为 true，这意味着强制执行安全重新协商。如果 SecureRenegotiate 为 false，则如果可能，仍然会使用安全重新协商，但如果对等方不支持 RFC 5746，则会回退到不安全的重新协商。

• {user_lookup_fun, {LookupFun, UserState}} - PSK/SRP 密码套件选项

  查找函数定义如下

  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.

  对于预共享密钥 (PSK) 密码套件，客户端和服务器都会调用查找函数来确定共享密钥。当客户端调用时，PSKIdentity 是服务器提供的提示或 undefined。当服务器调用时，PSKIdentity 是客户端提供的身份。

  对于安全远程密码 (SRP)，该函数仅由服务器用于获取其用于生成会话密钥的参数。DerivedKey 应根据 RFC 2945 和 RFC 5054 派生：crypto:sha([Salt, crypto:sha([Username, <<$:>>, Password])])

-type common_option_tls13() ::
          {supported_groups, [group()]} | {key_update_at, KeyUpdateAt :: pos_integer()}.

客户端和服务器都通用的 TLS-1.3 的选项。

• {supported_groups, Groups} - 密钥交换选项

  TLS 1.3 引入了 "supported_groups" 扩展，用于在 TLS 1.3 握手中协商 Diffie-Hellman 参数。客户端和服务器都可以指定它们愿意使用的参数列表。

  如果未指定，它将使用基于已安装的加密库版本过滤的默认列表 ([x25519, x448, secp256r1, secp384r1])。

• {key_update_at, KeyUpdateAt} - 会话密钥更新

  配置在执行自动密钥更新之前可以在 TLS 1.3 连接上发送的最大字节数。

  在给定的密钥集下，可以安全加密的明文数量存在密码学限制。当前默认设置确保数据完整性被破坏的概率不大于 1/2^57。有关更多信息，请参阅 TLS 中认证加密使用的限制。