常见 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

(repeated string) 如果指定，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

(repeated string) 如果指定，TLS 连接将仅支持指定的 ECDH 曲线。如果未指定，将使用默认曲线。

在非 FIPS 版本中，默认曲线为

X25519
P-256

在使用 BoringSSL FIPS 的版本中，默认曲线为

P-256

signature_algorithms

(repeated string) 如果指定，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: (DEFAULT) ⁣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: (string, REQUIRED) 私钥方法提供程序名称。该名称必须与支持的私钥方法提供程序类型匹配。

typed_config: (Any) 私钥方法提供程序特定配置。

fallback: (bool) 如果私钥提供程序不可用（例如，所需的硬件功能不存在），则当 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 使用。由于 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

(重复 config.core.v3.DataSource, 必需) 用于加密和解密 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, 必需) 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 类型设置，它将被忽略。

Enum 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: (默认) ⁣

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 验证。

有关常见系统 CA 位置的列表，请参阅 TLS 概述。

如果 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

(重复 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

(重复 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

(重复 extensions.transport_sockets.tls.v3.SubjectAltNameMatcher) 一个可选的主体备用名称匹配器列表。如果指定，Envoy 将验证提供的证书的主体备用名称是否与指定的匹配器之一匹配。匹配使用“任何”语义，也就是说，如果至少匹配一个匹配器，则验证 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: (重复 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: (bool) 如果指定，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: (bool) 如果此选项设置为 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]

Enum extensions.transport_sockets.tls.v3.CertificateValidationContext.TrustChainVerification

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

对等证书验证模式。

VERIFY_TRUST_CHAIN: (默认) ⁣执行默认证书验证（例如，针对 CA / 验证列表）。

ACCEPT_UNTRUSTED: ⁣允许证书验证失败的连接。对于 HTTP 连接，证书验证的结果可用于路由匹配。（参见 validated）。