常見 TLS 設定 (proto)

extensions.transport_sockets.tls.v3.TlsParameters

[extensions.transport_sockets.tls.v3.TlsParameters proto]

{
  "tls_minimum_protocol_version": ...,
  "tls_maximum_protocol_version": ...,
  "cipher_suites": [],
  "ecdh_curves": [],
  "signature_algorithms": []
}

tls_minimum_protocol_version

(extensions.transport_sockets.tls.v3.TlsParameters.TlsProtocol) 最小 TLS 協定版本。預設情況下，用戶端和伺服器皆為 TLSv1_2。

低於 TLSv1_2 的 TLS 協定版本需要使用 cipher_suites 設定設定相容的密碼，因為預設密碼不再包含相容的密碼。

注意

使用低於 TLSv1_2 的 TLS 協定版本存在嚴重的安全性考量和風險。

tls_maximum_protocol_version: (extensions.transport_sockets.tls.v3.TlsParameters.TlsProtocol) 最大 TLS 協定版本。預設情況下，用戶端為 TLSv1_2，伺服器為 TLSv1_3。

cipher_suites

(重複字串) 如果指定，TLS 監聽器在協商 TLS 1.0-1.2 時僅支援指定的密碼列表 (此設定在協商 TLS 1.3 時無效)。

如果未指定，將使用預設列表。伺服器 (下游) 和用戶端 (上游) TLS 設定的預設值不同。預設值會隨著時間的推移而根據安全性考量而變更；如果您在意，請設定它而不是使用預設值。

在非 FIPS 版本中，預設的伺服器密碼列表為

[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]
[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384

在使用 BoringSSL FIPS 的版本中，預設的伺服器密碼列表為

ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384

在非 FIPS 版本中，預設的用戶端密碼列表為

[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]
[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384

在使用 BoringSSL FIPS 的版本中，預設的用戶端密碼列表為

ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384

ecdh_curves

(重複字串) 如果指定，TLS 連線將僅支援指定的 ECDH 曲線。如果未指定，將使用預設曲線。

在非 FIPS 版本中，預設曲線為

X25519
P-256

在使用 BoringSSL FIPS 的版本中，預設曲線為

P-256

signature_algorithms

(重複字串) 如果指定，TLS 連線將僅支援指定的簽名演算法。列表會依喜好順序排列。如果未指定，將使用 BoringSSL 定義的預設簽名演算法。

BoringSSL 選取的預設簽名演算法 (可能過時)

ecdsa_secp256r1_sha256
rsa_pss_rsae_sha256
rsa_pkcs1_sha256
ecdsa_secp384r1_sha384
rsa_pss_rsae_sha384
rsa_pkcs1_sha384
rsa_pss_rsae_sha512
rsa_pkcs1_sha512
rsa_pkcs1_sha1

BoringSSL 支援的簽名演算法 (可能過時)

rsa_pkcs1_sha256
rsa_pkcs1_sha384
rsa_pkcs1_sha512
ecdsa_secp256r1_sha256
ecdsa_secp384r1_sha384
ecdsa_secp521r1_sha512
rsa_pss_rsae_sha256
rsa_pss_rsae_sha384
rsa_pss_rsae_sha512
ed25519
rsa_pkcs1_sha1
ecdsa_sha1

列舉 extensions.transport_sockets.tls.v3.TlsParameters.TlsProtocol

[extensions.transport_sockets.tls.v3.TlsParameters.TlsProtocol proto]

TLS_AUTO: (預設) ⁣Envoy 將選擇最佳的 TLS 版本。

TLSv1_0: ⁣TLS 1.0

TLSv1_1: ⁣TLS 1.1

TLSv1_2: ⁣TLS 1.2

TLSv1_3: ⁣TLS 1.3

extensions.transport_sockets.tls.v3.PrivateKeyProvider

[extensions.transport_sockets.tls.v3.PrivateKeyProvider proto]

BoringSSL 私密金鑰方法設定。私密金鑰方法用於外部 (可能為非同步) 簽署和解密作業。私密金鑰方法的一些用例包括 TPM 支援和 TLS 加速。

{
  "provider_name": ...,
  "typed_config": {...},
  "fallback": ...
}

provider_name: (字串，必要) 私密金鑰方法供應商名稱。該名稱必須與支援的私密金鑰方法供應商類型相符。

typed_config: (Any) 私密金鑰方法供應商特定設定。

fallback: (布林值) 如果私密金鑰供應商不可用 (例如，所需硬體功能不存在)，當 fallback 為 true 時，Envoy 將回退到 BoringSSL 預設實作。預設值為 false。

extensions.transport_sockets.tls.v3.TlsCertificate

[extensions.transport_sockets.tls.v3.TlsCertificate proto]

{
  "certificate_chain": {...},
  "private_key": {...},
  "pkcs12": {...},
  "watched_directory": {...},
  "private_key_provider": {...},
  "password": {...},
  "ocsp_staple": {...}
}

certificate_chain

(config.core.v3.DataSource) TLS 憑證鏈。

如果 certificate_chain 是檔案系統路徑，則會在父目錄中新增一個監看，以支援任何檔案移動以進行輪換。這目前僅適用於動態密碼，當 TlsCertificate 透過 SDS 傳遞時。

private_key

(config.core.v3.DataSource) TLS 私密金鑰。

如果 private_key 是檔案系統路徑，則會在父目錄中新增一個監看，以支援任何檔案移動以進行輪換。這目前僅適用於動態密碼，當 TlsCertificate 透過 SDS 傳遞時。

pkcs12

(config.core.v3.DataSource) 包含 TLS 憑證、鏈和私密金鑰的 Pkcs12 資料。

如果 pkcs12 是檔案系統路徑，將讀取該檔案，但不會在父目錄中新增任何監看，因為 pkcs12 不會被 SDS 使用。此欄位與 certificate_chain、private_key 和 private_key_provider 互斥。由於 API 相容性原因，無法將其標記為 oneof。設定 private_key、certificate_chain 或 private_key_provider 和 pkcs12 欄位都將導致錯誤。使用 password 來指定解密 PKCS12 資料的密碼 (如有必要)。

watched_directory: (config.core.v3.WatchedDirectory) 如果指定，基於檔案的 certificate_chain 和 private_key 來源的更新將由此監看觸發。憑證/金鑰對將一起讀取，並驗證原子讀取一致性 (即，憑證/金鑰讀取之間沒有發生干預修改，透過檔案雜湊比較來驗證)。這允許明確控制監看路徑，如果未指定此欄位，預設情況下將監看 certificate_chain 和 private_key 中檔案系統路徑的父目錄。這僅適用於當 TlsCertificate 透過 SDS 傳遞並參照檔案系統路徑時。請參閱 SDS 金鑰輪換文件以了解更多詳細資訊。

private_key_provider: (extensions.transport_sockets.tls.v3.PrivateKeyProvider) BoringSSL 私密金鑰方法供應商。這是 private_key 欄位的替代方案。由於 API 相容性原因，無法將其標記為 oneof。設定 private_key 和 private_key_provider 欄位都會導致錯誤。

password: (config.core.v3.DataSource) 解密 TLS 私密金鑰的密碼。如果未設定此欄位，則假設 TLS 私密金鑰未加密。

ocsp_staple: (config.core.v3.DataSource) 在握手期間要與此憑證一起釘選的 OCSP 回應。回應必須是 DER 編碼，並且只能透過 filename 或 inline_bytes 提供。回應可能僅適用於一個憑證。

extensions.transport_sockets.tls.v3.TlsSessionTicketKeys

[extensions.transport_sockets.tls.v3.TlsSessionTicketKeys proto]

{
  "keys": []
}

keys

(repeated config.core.v3.DataSource, REQUIRED) 用於加密和解密 TLS 會話票證的金鑰。陣列中的第一個金鑰包含用於加密此內容建立的所有新會話的金鑰。所有金鑰都是解密收到的票證的候選金鑰。這樣可以輕鬆輪換金鑰，例如，將新金鑰放在第一位，將先前的金鑰放在第二位。

如果未指定 session_ticket_keys，TLS 函式庫仍然會支援透過票證恢復會話，但它會使用內部產生和管理的金鑰，因此無法在熱重啟或不同主機上恢復會話。

每個金鑰必須包含確切的 80 位元組加密安全的隨機資料。例如，openssl rand 80 的輸出。

注意

使用此功能具有嚴重的安全性考量和風險。不當處理金鑰可能會導致連線的機密性遺失，即使使用支援完美前向保密性的密碼也是如此。請參閱 https://www.imperialviolet.org/2013/06/27/botchingpfs.html 以獲得一些討論。為了將風險降到最低，您必須

保持會話票證金鑰的安全性至少與您的 TLS 憑證私密金鑰一樣安全
至少每天輪換會話票證金鑰，最好是每小時輪換
始終使用加密安全的隨機資料來源產生金鑰

extensions.transport_sockets.tls.v3.SubjectAltNameMatcher

[extensions.transport_sockets.tls.v3.SubjectAltNameMatcher proto]

用於主體替代名稱的匹配器，以匹配 SAN 的類型和值。

{
  "san_type": ...,
  "matcher": {...},
  "oid": ...
}

san_type: (extensions.transport_sockets.tls.v3.SubjectAltNameMatcher.SanType) SAN 類型的規格。請注意，預設的列舉值是無效的選擇。

matcher

(type.matcher.v3.StringMatcher, REQUIRED) SAN 值的匹配器。

對 OTHER_NAME SAN 值進行字串匹配取決於它們的 ASN.1 類型

OBJECT：針對其點式數字表示法進行驗證 (例如，「1.2.3.4」)

BOOLEAN：針對字串「true」或「false」進行驗證

INTEGER/ENUMERATED：針對包含整數值的字串進行驗證

NULL：針對空字串進行驗證

其他類型：直接針對字串值進行驗證

oid

(string) 如果使用 OTHER_NAME SAN 類型，則為必要的值 OID。例如，UPN OID 為 1.3.6.1.4.1.311.20.2.3 (參考：http://oid-info.com/get/1.3.6.1.4.1.311.20.2.3)。

如果為 OTHER_NAME 以外的 SAN 類型設定，則會忽略它。

列舉 extensions.transport_sockets.tls.v3.SubjectAltNameMatcher.SanType

[extensions.transport_sockets.tls.v3.SubjectAltNameMatcher.SanType proto]

指示 RFC 5280 第 4.2.1.5 節中定義的 GeneralName 的選擇，以便進行比對。

SAN_TYPE_UNSPECIFIED: (DEFAULT) ⁣

EMAIL: ⁣

DNS: ⁣

URI: ⁣

IP_ADDRESS: ⁣

OTHER_NAME: ⁣

extensions.transport_sockets.tls.v3.CertificateValidationContext

[extensions.transport_sockets.tls.v3.CertificateValidationContext proto]

{
  "trusted_ca": {...},
  "watched_directory": {...},
  "verify_certificate_spki": [],
  "verify_certificate_hash": [],
  "match_typed_subject_alt_names": [],
  "match_subject_alt_names": [],
  "crl": {...},
  "allow_expired_certificate": ...,
  "trust_chain_verification": ...,
  "custom_validator_config": {...},
  "only_verify_leaf_cert_crl": ...,
  "max_verify_depth": {...}
}

trusted_ca

(config.core.v3.DataSource) 包含憑證授權單位憑證的 TLS 憑證資料，用於驗證呈現的對等憑證（例如，叢集的伺服器憑證或接聽程式的用戶端憑證）。如果未指定，且呈現對等憑證，則不會驗證。預設情況下，用戶端憑證是選用的，除非也指定了其他選項之一 (require_client_certificate、verify_certificate_spki、verify_certificate_hash 或 match_typed_subject_alt_names)。

它也可以選擇包含憑證撤銷清單，在這種情況下，Envoy 將驗證呈現的對等憑證是否尚未被其中一個包含的 CRL 撤銷。請注意，如果在信任鏈中為任何憑證授權單位提供 CRL，則必須為該鏈中的所有憑證授權單位提供 CRL。如果未這樣做，將導致該鏈中已撤銷和未撤銷憑證的驗證失敗。可以通過將 only_verify_leaf_cert_crl 設定為 true 來更改要求所有憑證都包含 CRL 的行為。如果設定為 true，則只有鏈中的最後一個憑證會進行 CRL 驗證。

請參閱 TLS 概述，以取得常見的系統 CA 位置清單。

如果 trusted_ca 是檔案系統路徑，則會在父目錄新增監視，以支援任何檔案移動以進行輪換。這目前僅適用於動態秘密，當 CertificateValidationContext 透過 SDS 傳遞時。

預設情況下會設定 X509_V_FLAG_PARTIAL_CHAIN，因此 trusted_ca 中的非根/中繼 CA 憑證也可以視為信任錨點。它允許通過建立有效的局部鏈而不是完整鏈進行驗證。

如果設定了 ca_certificate_provider_instance，它將優先於 trusted_ca。

watched_directory: (config.core.v3.WatchedDirectory) 如果指定，則此監視將觸發基於檔案的 trusted_ca 來源的更新。這允許對監視的路徑進行明確控制，預設情況下，如果未指定此欄位，則會監視 trusted_ca 中檔案系統路徑的父目錄。這僅適用於當 CertificateValidationContext 由 SDS 交付並參考檔案系統路徑時。請參閱 SDS 金鑰輪換文件以了解更多詳細資訊。

verify_certificate_spki

(repeated string) base64 編碼的 SHA-256 雜湊的可選清單。如果指定，Envoy 將驗證呈現的憑證的 DER 編碼的主體公鑰資訊 (SPKI) 的 SHA-256 是否與其中一個指定的值匹配。

可以使用以下命令產生憑證主體公鑰資訊 (SPKI) 的 base64 編碼的 SHA-256

$ openssl x509 -in path/to/client.crt -noout -pubkey
  | openssl pkey -pubin -outform DER
  | openssl dgst -sha256 -binary
  | openssl enc -base64
NvqYIYSbgK2vCJpQhObf77vv+bQWtc5ek5RIOwPiC9A=

這是 HTTP 公鑰釘選中使用的格式。

當同時指定：verify_certificate_hash 和 verify_certificate_spki 時，只要從任一清單中找到匹配的值，就會接受該憑證。

注意

此選項優於 verify_certificate_hash，因為 SPKI 與私密金鑰關聯，因此當使用相同的私密金鑰更新憑證時，它不會變更。

verify_certificate_hash

(repeated string) 十六進位編碼的 SHA-256 雜湊的可選清單。如果指定，Envoy 將驗證呈現的憑證的 DER 編碼的 SHA-256 是否與其中一個指定的值匹配。

可以使用以下命令產生憑證的十六進位編碼的 SHA-256

$ openssl x509 -in path/to/client.crt -outform DER | openssl dgst -sha256 | cut -d" " -f2
df6ff72fe9116521268f6f2dd4966f51df479883fe7037b39f75916ac3049d1a

可以使用以下命令產生憑證的長十六進位編碼和冒號分隔的 SHA-256 (又稱「指紋」)

$ openssl x509 -in path/to/client.crt -noout -fingerprint -sha256 | cut -d"=" -f2
DF:6F:F7:2F:E9:11:65:21:26:8F:6F:2D:D4:96:6F:51:DF:47:98:83:FE:70:37:B3:9F:75:91:6A:C3:04:9D:1A

這兩種格式都是可接受的。

當同時指定：verify_certificate_hash 和 verify_certificate_spki 時，只要從任一清單中找到匹配的值，就會接受該憑證。

match_typed_subject_alt_names

(repeated extensions.transport_sockets.tls.v3.SubjectAltNameMatcher) 主體替代名稱匹配器的可選清單。如果指定，Envoy 將驗證呈現的憑證的主體替代名稱是否與其中一個指定的匹配器匹配。匹配使用「any」語意，也就是說，如果至少匹配一個匹配器，則會驗證 SAN。

當憑證具有萬用字元 DNS SAN 項目時，若要匹配特定的用戶端，應在字串匹配器中使用精確匹配類型進行設定。例如，如果憑證具有「*.example.com」作為 DNS SAN 項目，若要僅允許「api.example.com」，則應將其設定如下所示。

match_typed_subject_alt_names:
- san_type: DNS
  matcher:
    exact: "api.example.com"

注意

主體替代名稱很容易被竄改，因此僅驗證它們是不安全的，因此此選項必須與 trusted_ca 一起使用。

match_subject_alt_names: (repeated type.matcher.v3.StringMatcher) 此欄位已棄用，改為使用 match_typed_subject_alt_names。請注意，如果同時指定此欄位和 match_typed_subject_alt_names，則會忽略前者 (已棄用的欄位)。

crl

(config.core.v3.DataSource) 可選的憑證撤銷清單 (PEM 格式)。如果指定，Envoy 將驗證呈現的對等憑證是否尚未被此 CRL 撤銷。如果此 DataSource 包含多個 CRL，則會使用所有 CRL。請注意，如果在信任鏈中為任何憑證授權單位提供 CRL，則必須為該鏈中的所有憑證授權單位提供 CRL。如果未這樣做，將導致該鏈中已撤銷和未撤銷憑證的驗證失敗。可以透過將 only_verify_leaf_cert_crl 設定為 true 來更改此預設行為。

如果 crl 是一個檔案系統路徑，則會在其父目錄上新增一個監看，以支援任何檔案移動以進行輪替。目前這僅適用於動態密鑰，當 CertificateValidationContext 是透過 SDS 傳遞時。

allow_expired_certificate: (布林值) 如果指定，Envoy 將不會拒絕過期的憑證。

trust_chain_verification: (extensions.transport_sockets.tls.v3.CertificateValidationContext.TrustChainVerification) 憑證信任鏈驗證模式。

custom_validator_config

(config.core.v3.TypedExtensionConfig) 特定憑證驗證器的擴充功能設定。如果指定，則所有驗證都由指定的驗證器執行，並且所有其他驗證設定的行為都由指定的驗證器定義（並且可能會完全忽略、未使用且未驗證）。請參閱指定驗證器的文件。如果您不想要自訂驗證演算法，請勿設定此欄位。

提示

此擴充功能類別具有以下已知擴充功能

envoy.tls.cert_validator.spiffe

only_verify_leaf_cert_crl: (布林值) 如果此選項設定為 true，則只有憑證鏈結末端的憑證會受到 CRL 的驗證。

max_verify_depth: (UInt32Value) 定義驗證中接受的憑證鏈結最大深度，預設限制為 100，儘管這可能取決於系統。此數字不包含葉節點，但包含信任錨點，因此深度為 1 表示允許葉節點和一個 CA 憑證。如果信任的簽發者出現在鏈結中，但深度大於配置的深度，則憑證驗證將會失敗。這與 OpenSSL 1.0.x 和較舊版本的 BoringSSL 中的 SSL_CTX_set_verify_depth 的語意相符。它與 OpenSSL 1.1.x 和較新版本的 BoringSSL 中的 SSL_CTX_set_verify_depth 不同之處在於，它包含信任錨點。信任的簽發者是透過設定 trusted_ca 來指定

extensions.transport_sockets.tls.v3.CertificateValidationContext.SystemRootCerts

[extensions.transport_sockets.tls.v3.CertificateValidationContext.SystemRootCerts proto]

列舉 extensions.transport_sockets.tls.v3.CertificateValidationContext.TrustChainVerification

[extensions.transport_sockets.tls.v3.CertificateValidationContext.TrustChainVerification proto]

同儕憑證驗證模式。

VERIFY_TRUST_CHAIN: （預設） 執行預設憑證驗證（例如，針對 CA / 驗證列表）。

ACCEPT_UNTRUSTED: ⁣將允許憑證驗證失敗的連線。對於 HTTP 連線，憑證驗證的結果可用於路由匹配。（請參閱 validated）。