-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 和各種交握機密。

  預設會停用 (false) keep_secrets 功能。

  在 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 選項。

  設定 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。如果為相同的簽章演算法提供多個金鑰，它們將依強度設定優先順序 (引擎金鑰 除外；請參閱下一段)。這提供彈性，例如，設定預期在大多數情況下使用的新憑證，以及僅用於與舊系統通訊的較舊但可接受的憑證。請注意，誘導的額外負擔與彈性之間存在權衡；因此，應基於充分的理由選擇替代方案。

  引擎金鑰 將優先於其他金鑰。由於無法檢查引擎金鑰，因此提供多個引擎金鑰沒有意義。

  指定此選項時，它會覆寫所有單一憑證和金鑰選項。如需範例，請參閱 使用者指南。

  注意

  只有不支援 dsa 憑證的 TLS-1.3 實作才支援 eddsa 憑證。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

  當 X.509 路徑驗證發生錯誤或遇到 SSL 應用程式未知的擴展時，會呼叫驗證函式。當路徑驗證認為憑證有效時，也會呼叫此函式，以允許使用者應用程式存取路徑中的每個憑證。它會使用 valid_peer 或 valid 作為驗證函式的 Event 參數，來區分對等憑證和 CA 憑證。關於 #'OTPCertificate'{} 和 #'Extension'{} 的定義，請參閱 Public_Key 使用者指南。

  • 如果驗證回呼函式傳回 {fail, Reason}，驗證過程會立即停止，並向對等方傳送警示，且 TLS/DTLS 交握會終止。
  • 如果驗證回呼函式傳回 {valid, UserState}，驗證過程會繼續。
  • 如果驗證回呼函式始終傳回 {valid, UserState}，則無論驗證是否失敗，TLS/DTLS 交握都不會終止，並且會建立連線。
  • 如果使用使用者應用程式未知的擴展呼叫，則該函式應傳回 {unknown, UserState}。

  請注意，如果函式針對標記為 critical 的擴展傳回 unknown，則驗證將會失敗。

  在 verify_peer mode 中的預設選項 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 憑證指定了擴展金鑰用法擴展，並且沒有根據與此 CA 連鎖的對等方的角色，包含作為 TLS 伺服器 (id-kp-ServerAuth) 或 TLS 用戶端 (id-kp-ClientAuth) 的用途，或者選項 allow_any_ca_purpose 設定為 true，但 CA 憑證用途中不包含特殊的 any 值 (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 中經驗證的加密使用的限制。