TLS transport socket (proto)

This extension has the qualified name envoy.transport_sockets.tls

Note

This extension is intended to be robust against both untrusted downstream and upstream traffic.

Tip

This extension extends and can be used with the following extension categories:

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext

The TLS contexts below provide the transport socket configuration for upstream/downstream TLS.

extensions.transport_sockets.tls.v3.UpstreamTlsContext

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

{
  "common_tls_context": {...},
  "sni": ...,
  "auto_host_sni": ...,
  "auto_sni_san_validation": ...,
  "allow_renegotiation": ...,
  "max_session_keys": {...},
  "enforce_rsa_key_usage": {...}
}

common_tls_context: (extensions.transport_sockets.tls.v3.CommonTlsContext) Common TLS context settings.

Attention

Server certificate verification is not enabled by default. Configure trusted_ca to enable verification.

sni: (string) SNI string to use when creating TLS backend connections.

auto_host_sni

(bool) If true, replaces the SNI for the connection with the hostname of the upstream host, if the hostname is known due to either a DNS cluster type or the hostname is set on the host.

See SNI configuration for details on how this interacts with other validation options.

auto_sni_san_validation

(bool) If true, replace any Subject Alternative Name validations with a validation for a DNS SAN matching the SNI value sent. Note that the validation will be against the actual requested SNI, regardless of how it is configured.

For the common case where an SNI value is sent and it is expected that the server certificate contains a SAN matching that SNI value, this option will do the correct SAN validation.

See validation configuration for how this interacts with other validation options.

allow_renegotiation: (bool) If true, server-initiated TLS renegotiation will be allowed.

Attention

TLS renegotiation is considered insecure and shouldn’t be used unless absolutely necessary.

max_session_keys

(UInt32Value) Maximum number of session keys (Pre-Shared Keys for TLSv1.3+, Session IDs and Session Tickets for TLSv1.2 and older) to store for the purpose of session resumption.

Defaults to 1, setting this to 0 disables session resumption.

enforce_rsa_key_usage: (BoolValue) This field is used to control the enforcement, whereby the handshake will fail if the keyUsage extension is present and incompatible with the TLS usage. Currently, the default value is false (i.e., enforcement off) but it is expected to be changed to true by default in a future release. ssl.was_key_usage_invalid in listener metrics will be set for certificate configurations that would fail if this option were set to true.

extensions.transport_sockets.tls.v3.DownstreamTlsContext

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

{
  "common_tls_context": {...},
  "require_client_certificate": {...},
  "session_ticket_keys": {...},
  "session_ticket_keys_sds_secret_config": {...},
  "disable_stateless_session_resumption": ...,
  "disable_stateful_session_resumption": ...,
  "session_timeout": {...},
  "ocsp_staple_policy": ...,
  "full_scan_certs_on_sni_mismatch": {...},
  "prefer_client_ciphers": ...
}

common_tls_context: (extensions.transport_sockets.tls.v3.CommonTlsContext) Common TLS context settings.

require_client_certificate: (BoolValue) If specified, Envoy will reject connections without a valid client certificate.

session_ticket_keys

(extensions.transport_sockets.tls.v3.TlsSessionTicketKeys) TLS session ticket key settings.

Only one of session_ticket_keys, session_ticket_keys_sds_secret_config, disable_stateless_session_resumption may be set.

session_ticket_keys_sds_secret_config

(extensions.transport_sockets.tls.v3.SdsSecretConfig) Config for fetching TLS session ticket keys via SDS API.

Only one of session_ticket_keys, session_ticket_keys_sds_secret_config, disable_stateless_session_resumption may be set.

disable_stateless_session_resumption

(bool) Config for controlling stateless TLS session resumption: setting this to true will cause the TLS server to not issue TLS session tickets for the purposes of stateless TLS session resumption. If set to false, the TLS server will issue TLS session tickets and encrypt/decrypt them using the keys specified through either session_ticket_keys or session_ticket_keys_sds_secret_config. If this config is set to false and no keys are explicitly configured, the TLS server will issue TLS session tickets and encrypt/decrypt them using an internally-generated and managed key, with the implication that sessions cannot be resumed across hot restarts or on different hosts.

Only one of session_ticket_keys, session_ticket_keys_sds_secret_config, disable_stateless_session_resumption may be set.

disable_stateful_session_resumption: (bool) If set to true, the TLS server will not maintain a session cache of TLS sessions. (This is relevant only for TLSv1.2 and earlier.)

session_timeout: (Duration) If specified, session_timeout will change the maximum lifetime (in seconds) of the TLS session. Currently this value is used as a hint for the TLS session ticket lifetime (for TLSv1.2). Only seconds can be specified (fractional seconds are ignored).

ocsp_staple_policy: (extensions.transport_sockets.tls.v3.DownstreamTlsContext.OcspStaplePolicy) Config for whether to use certificates if they do not have an accompanying OCSP response or if the response expires at runtime. Defaults to LENIENT_STAPLING

full_scan_certs_on_sni_mismatch: (BoolValue) Multiple certificates are allowed in Downstream transport socket to serve different SNI. If the client provides SNI but no such cert matched, it will decide to full scan certificates or not based on this config. Defaults to false. See more details in Multiple TLS certificates.

prefer_client_ciphers: (bool) By default, Envoy as a server uses its preferred cipher during the handshake. Setting this to true would allow the downstream client’s preferred cipher to be used instead. Has no effect when using TLSv1_3.

Enum extensions.transport_sockets.tls.v3.DownstreamTlsContext.OcspStaplePolicy

[extensions.transport_sockets.tls.v3.DownstreamTlsContext.OcspStaplePolicy proto]

LENIENT_STAPLING: (DEFAULT) ⁣OCSP responses are optional. If an OCSP response is absent or expired, the associated certificate will be used for connections without an OCSP staple.

STRICT_STAPLING: ⁣OCSP responses are optional. If an OCSP response is absent, the associated certificate will be used without an OCSP staple. If a response is provided but is expired, the associated certificate will not be used for subsequent connections. If no suitable certificate is found, the connection is rejected.

MUST_STAPLE: ⁣OCSP responses are required. Configuration will fail if a certificate is provided without an OCSP response. If a response expires, the associated certificate will not be used connections. If no suitable certificate is found, the connection is rejected.

extensions.transport_sockets.tls.v3.TlsKeyLog

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

TLS key log configuration. The key log file format is “format used by NSS for its SSLKEYLOGFILE debugging output” (text taken from openssl man page)

{
  "path": ...,
  "local_address_range": [],
  "remote_address_range": []
}

path: (string, REQUIRED) The path to save the TLS key log.

local_address_range: (repeated config.core.v3.CidrRange) The local IP address that will be used to filter the connection which should save the TLS key log If it is not set, any local IP address will be matched.

remote_address_range: (repeated config.core.v3.CidrRange) The remote IP address that will be used to filter the connection which should save the TLS key log If it is not set, any remote IP address will be matched.

extensions.transport_sockets.tls.v3.CommonTlsContext

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

TLS context shared by both client and server TLS contexts.

{
  "tls_params": {...},
  "tls_certificates": [],
  "tls_certificate_sds_secret_configs": [],
  "custom_tls_certificate_selector": {...},
  "validation_context": {...},
  "validation_context_sds_secret_config": {...},
  "combined_validation_context": {...},
  "alpn_protocols": [],
  "custom_handshaker": {...},
  "key_log": {...}
}

tls_params: (extensions.transport_sockets.tls.v3.TlsParameters) TLS protocol versions, cipher suites etc.

tls_certificates

(repeated extensions.transport_sockets.tls.v3.TlsCertificate) Only a single TLS certificate is supported in client contexts. In server contexts, Multiple TLS certificates can be associated with the same context to allow both RSA and ECDSA certificates and support SNI-based selection.

If tls_certificate_provider_instance is set, this field is ignored. If this field is set, tls_certificate_sds_secret_configs is ignored.

tls_certificate_sds_secret_configs

(repeated extensions.transport_sockets.tls.v3.SdsSecretConfig) Configs for fetching TLS certificates via SDS API. Note SDS API allows certificates to be fetched/refreshed over the network asynchronously with respect to the TLS handshake.

The same number and types of certificates as tls_certificates are valid in the the certificates fetched through this setting.

If tls_certificates or tls_certificate_provider_instance are set, this field is ignored.

custom_tls_certificate_selector

(config.core.v3.TypedExtensionConfig) Custom TLS certificate selector.

Select TLS certificate based on TLS client hello. If empty, defaults to native TLS certificate selection behavior: DNS SANs or Subject Common Name in TLS certificates is extracted as server name pattern to match SNI.

validation_context

(extensions.transport_sockets.tls.v3.CertificateValidationContext) How to validate peer certificates.

Only one of validation_context, validation_context_sds_secret_config, combined_validation_context may be set.

validation_context_sds_secret_config

(extensions.transport_sockets.tls.v3.SdsSecretConfig) Config for fetching validation context via SDS API. Note SDS API allows certificates to be fetched/refreshed over the network asynchronously with respect to the TLS handshake.

Only one of validation_context, validation_context_sds_secret_config, combined_validation_context may be set.

combined_validation_context

(extensions.transport_sockets.tls.v3.CommonTlsContext.CombinedCertificateValidationContext) Combined certificate validation context holds a default CertificateValidationContext and SDS config. When SDS server returns dynamic CertificateValidationContext, both dynamic and default CertificateValidationContext are merged into a new CertificateValidationContext for validation. This merge is done by Message::MergeFrom(), so dynamic CertificateValidationContext overwrites singular fields in default CertificateValidationContext, and concatenates repeated fields to default CertificateValidationContext, and logical OR is applied to boolean fields.

Only one of validation_context, validation_context_sds_secret_config, combined_validation_context may be set.

alpn_protocols

(repeated string) Supplies the list of ALPN protocols that the listener should expose. In practice this is likely to be set to one of two values (see the codec_type parameter in the HTTP connection manager for more information):

“h2,http/1.1” If the listener is going to support both HTTP/2 and HTTP/1.1.
“http/1.1” If the listener is only going to support HTTP/1.1.

There is no default for this parameter. If empty, Envoy will not expose ALPN.

custom_handshaker: (config.core.v3.TypedExtensionConfig) Custom TLS handshaker. If empty, defaults to native TLS handshaking behavior.

key_log: (extensions.transport_sockets.tls.v3.TlsKeyLog) TLS key log configuration

extensions.transport_sockets.tls.v3.CommonTlsContext.CombinedCertificateValidationContext

[extensions.transport_sockets.tls.v3.CommonTlsContext.CombinedCertificateValidationContext proto]

{
  "default_validation_context": {...},
  "validation_context_sds_secret_config": {...}
}

default_validation_context: (extensions.transport_sockets.tls.v3.CertificateValidationContext, REQUIRED) How to validate peer certificates.

validation_context_sds_secret_config: (extensions.transport_sockets.tls.v3.SdsSecretConfig, REQUIRED) Config for fetching validation context via SDS API. Note SDS API allows certificates to be fetched/refreshed over the network asynchronously with respect to the TLS handshake.