.. _envoy_v3_api_file_envoy/extensions/transport_sockets/tls/v3/tls.proto: TLS transport socket ==================== .. _extension_envoy.transport_sockets.tls: This extension may be referenced by the qualified name *envoy.transport_sockets.tls* .. note:: This extension is intended to be robust against both untrusted downstream and upstream traffic. The TLS contexts below provide the transport socket configuration for upstream/downstream TLS. .. _envoy_v3_api_msg_extensions.transport_sockets.tls.v3.UpstreamTlsContext: extensions.transport_sockets.tls.v3.UpstreamTlsContext ------------------------------------------------------ `[extensions.transport_sockets.tls.v3.UpstreamTlsContext proto] `_ .. code-block:: json { "common_tls_context": "{...}", "sni": "...", "allow_renegotiation": "...", "max_session_keys": "{...}" } .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.UpstreamTlsContext.common_tls_context: common_tls_context (:ref:`extensions.transport_sockets.tls.v3.CommonTlsContext `) Common TLS context settings. .. attention:: Server certificate verification is not enabled by default. Configure :ref:`trusted_ca` to enable verification. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.UpstreamTlsContext.sni: sni (`string `_) SNI string to use when creating TLS backend connections. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.UpstreamTlsContext.allow_renegotiation: 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. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.UpstreamTlsContext.max_session_keys: 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. .. _envoy_v3_api_msg_extensions.transport_sockets.tls.v3.DownstreamTlsContext: extensions.transport_sockets.tls.v3.DownstreamTlsContext -------------------------------------------------------- `[extensions.transport_sockets.tls.v3.DownstreamTlsContext proto] `_ .. code-block:: json { "common_tls_context": "{...}", "require_client_certificate": "{...}", "session_ticket_keys": "{...}", "session_ticket_keys_sds_secret_config": "{...}", "disable_stateless_session_resumption": "...", "session_timeout": "{...}" } .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.common_tls_context: common_tls_context (:ref:`extensions.transport_sockets.tls.v3.CommonTlsContext `) Common TLS context settings. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.require_client_certificate: require_client_certificate (`BoolValue `_) If specified, Envoy will reject connections without a valid client certificate. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.session_ticket_keys: session_ticket_keys (:ref:`extensions.transport_sockets.tls.v3.TlsSessionTicketKeys `) TLS session ticket key settings. Only one of :ref:`session_ticket_keys `, :ref:`session_ticket_keys_sds_secret_config `, :ref:`disable_stateless_session_resumption ` may be set. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.session_ticket_keys_sds_secret_config: session_ticket_keys_sds_secret_config (:ref:`extensions.transport_sockets.tls.v3.SdsSecretConfig `) Config for fetching TLS session ticket keys via SDS API. Only one of :ref:`session_ticket_keys `, :ref:`session_ticket_keys_sds_secret_config `, :ref:`disable_stateless_session_resumption ` may be set. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.disable_stateless_session_resumption: 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 :ref:`session_ticket_keys ` or :ref:`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 :ref:`session_ticket_keys `, :ref:`session_ticket_keys_sds_secret_config `, :ref:`disable_stateless_session_resumption ` may be set. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.session_timeout: session_timeout (`Duration `_) If specified, session_timeout will change maximum lifetime (in seconds) of TLS session Currently this value is used as a hint to `TLS session ticket lifetime (for TLSv1.2) ` only seconds could be specified (fractional seconds are going to be ignored). .. _envoy_v3_api_msg_extensions.transport_sockets.tls.v3.CommonTlsContext: extensions.transport_sockets.tls.v3.CommonTlsContext ---------------------------------------------------- `[extensions.transport_sockets.tls.v3.CommonTlsContext proto] `_ TLS context shared by both client and server TLS contexts. .. code-block:: json { "tls_params": "{...}", "tls_certificates": [], "tls_certificate_sds_secret_configs": [], "validation_context": "{...}", "validation_context_sds_secret_config": "{...}", "combined_validation_context": "{...}", "alpn_protocols": [] } .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.tls_params: tls_params (:ref:`extensions.transport_sockets.tls.v3.TlsParameters `) TLS protocol versions, cipher suites etc. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.tls_certificates: tls_certificates (:ref:`extensions.transport_sockets.tls.v3.TlsCertificate `) :ref:`Multiple TLS certificates ` can be associated with the same context to allow both RSA and ECDSA certificates. Only a single TLS certificate is supported in client contexts. In server contexts, the first RSA certificate is used for clients that only support RSA and the first ECDSA certificate is used for clients that support ECDSA. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.tls_certificate_sds_secret_configs: tls_certificate_sds_secret_configs (:ref:`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. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.validation_context: validation_context (:ref:`extensions.transport_sockets.tls.v3.CertificateValidationContext `) How to validate peer certificates. Only one of :ref:`validation_context `, :ref:`validation_context_sds_secret_config `, :ref:`combined_validation_context ` may be set. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.validation_context_sds_secret_config: validation_context_sds_secret_config (:ref:`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 :ref:`validation_context `, :ref:`validation_context_sds_secret_config `, :ref:`combined_validation_context ` may be set. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.combined_validation_context: combined_validation_context (:ref:`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 :ref:`validation_context `, :ref:`validation_context_sds_secret_config `, :ref:`combined_validation_context ` may be set. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.alpn_protocols: alpn_protocols (`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 :ref:`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. .. _envoy_v3_api_msg_extensions.transport_sockets.tls.v3.CommonTlsContext.CertificateProvider: extensions.transport_sockets.tls.v3.CommonTlsContext.CertificateProvider ------------------------------------------------------------------------ `[extensions.transport_sockets.tls.v3.CommonTlsContext.CertificateProvider proto] `_ Config for Certificate provider to get certificates. This provider should allow certificates to be fetched/refreshed over the network asynchronously with respect to the TLS handshake. .. code-block:: json { "name": "...", "typed_config": "{...}" } .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.CertificateProvider.name: name (`string `_, *REQUIRED*) opaque name used to specify certificate instances or types. For example, "ROOTCA" to specify a root-certificate (validation context) or "TLS" to specify a new tls-certificate. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.CertificateProvider.typed_config: typed_config (:ref:`config.core.v3.TypedExtensionConfig `, *REQUIRED*) Provider specific config. Note: an implementation is expected to dedup multiple instances of the same config to maintain a single certificate-provider instance. The sharing can happen, for example, among multiple clusters or between the tls_certificate and validation_context certificate providers of a cluster. This config could be supplied inline or (in future) a named xDS resource. .. _envoy_v3_api_msg_extensions.transport_sockets.tls.v3.CommonTlsContext.CombinedCertificateValidationContext: extensions.transport_sockets.tls.v3.CommonTlsContext.CombinedCertificateValidationContext ----------------------------------------------------------------------------------------- `[extensions.transport_sockets.tls.v3.CommonTlsContext.CombinedCertificateValidationContext proto] `_ .. code-block:: json { "default_validation_context": "{...}", "validation_context_sds_secret_config": "{...}" } .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.CombinedCertificateValidationContext.default_validation_context: default_validation_context (:ref:`extensions.transport_sockets.tls.v3.CertificateValidationContext `, *REQUIRED*) How to validate peer certificates. .. _envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.CombinedCertificateValidationContext.validation_context_sds_secret_config: validation_context_sds_secret_config (:ref:`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. Only to be used when validation_context_certificate_provider is not used.