package envoy.extensions.transport_sockets.tls.v3

Get desktop application:
View/edit binary Protocol Buffers messages

Indicates a certificate to be obtained from a named CertificateProvider plugin instance. The plugin instances are defined in the client's bootstrap file. The plugin allows certificates to be fetched/refreshed over the network asynchronously with respect to the TLS handshake. [#not-implemented-hide:]

Used in: CertificateValidationContext, CommonTlsContext

• string instance_name = 1

  Provider instance name. Instance names should generally be defined not in terms of the underlying provider implementation (e.g., "file_watcher") but rather in terms of the function of the certificates (e.g., "foo_deployment_identity").

• string certificate_name = 2

  Opaque name used to specify certificate instances or types. For example, "ROOTCA" to specify a root-certificate (validation context) or "example.com" to specify a certificate for a particular domain. Not all provider instances will actually use this field, so the value defaults to the empty string.

[#next-free-field: 18]

Used in: CommonTlsContext, CommonTlsContext.CombinedCertificateValidationContext, Secret

• optional config.core.v3.DataSource trusted_ca = 1

  TLS certificate data containing certificate authority certificates to use in verifying a presented peer certificate (e.g. server certificate for clusters or client certificate for listeners). If not specified and a peer certificate is presented it will not be verified. By default, a client certificate is optional, unless one of the additional options (:ref:`require_client_certificate <envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.require_client_certificate>`, :ref:`verify_certificate_spki <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_spki>`, :ref:`verify_certificate_hash <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>`, or :ref:`match_typed_subject_alt_names <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.match_typed_subject_alt_names>`) is also specified. It can optionally contain certificate revocation lists, in which case Envoy will verify that the presented peer certificate has not been revoked by one of the included CRLs. Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. The behavior of requiring all certificates to contain CRLs can be altered by setting :ref:`only_verify_leaf_cert_crl <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.only_verify_leaf_cert_crl>` true. If set to true, only the final certificate in the chain undergoes CRL verification. See :ref:`the TLS overview <arch_overview_ssl_enabling_verification>` for a list of common system CA locations. If ``trusted_ca`` is a filesystem path, a watch will be added to the parent directory for any file moves to support rotation. This currently only applies to dynamic secrets, when the ``CertificateValidationContext`` is delivered via SDS. X509_V_FLAG_PARTIAL_CHAIN is set by default, so non-root/intermediate ca certificate in ``trusted_ca`` can be treated as trust anchor as well. It allows verification with building valid partial chain instead of a full chain. If ``ca_certificate_provider_instance`` is set, it takes precedence over ``trusted_ca``.

• optional CertificateProviderPluginInstance ca_certificate_provider_instance = 13

  Certificate provider instance for fetching TLS certificates. If set, takes precedence over ``trusted_ca``. [#not-implemented-hide:]

• optional CertificateValidationContext.SystemRootCerts system_root_certs = 17

  Use system root certs for validation. If present, system root certs are used only if neither of the ``trusted_ca`` or ``ca_certificate_provider_instance`` fields are set. [#not-implemented-hide:]

• optional config.core.v3.WatchedDirectory watched_directory = 11

  If specified, updates of a file-based ``trusted_ca`` source will be triggered by this watch. This allows explicit control over the path watched, by default the parent directory of the filesystem path in ``trusted_ca`` is watched if this field is not specified. This only applies when a ``CertificateValidationContext`` is delivered by SDS with references to filesystem paths. See the :ref:`SDS key rotation <sds_key_rotation>` documentation for further details.

• repeated string verify_certificate_spki = 3

  An optional list of base64-encoded SHA-256 hashes. If specified, Envoy will verify that the SHA-256 of the DER-encoded Subject Public Key Information (SPKI) of the presented certificate matches one of the specified values. A base64-encoded SHA-256 of the Subject Public Key Information (SPKI) of the certificate can be generated with the following command: .. code-block:: bash $ openssl x509 -in path/to/client.crt -noout -pubkey | openssl pkey -pubin -outform DER | openssl dgst -sha256 -binary | openssl enc -base64 NvqYIYSbgK2vCJpQhObf77vv+bQWtc5ek5RIOwPiC9A= This is the format used in HTTP Public Key Pinning. When both: :ref:`verify_certificate_hash <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>` and :ref:`verify_certificate_spki <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_spki>` are specified, a hash matching value from either of the lists will result in the certificate being accepted. .. attention:: This option is preferred over :ref:`verify_certificate_hash <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>`, because SPKI is tied to a private key, so it doesn't change when the certificate is renewed using the same private key.

• repeated string verify_certificate_hash = 2

  An optional list of hex-encoded SHA-256 hashes. If specified, Envoy will verify that the SHA-256 of the DER-encoded presented certificate matches one of the specified values. A hex-encoded SHA-256 of the certificate can be generated with the following command: .. code-block:: bash $ openssl x509 -in path/to/client.crt -outform DER | openssl dgst -sha256 | cut -d" " -f2 df6ff72fe9116521268f6f2dd4966f51df479883fe7037b39f75916ac3049d1a A long hex-encoded and colon-separated SHA-256 (a.k.a. "fingerprint") of the certificate can be generated with the following command: .. code-block:: bash $ 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 Both of those formats are acceptable. When both: :ref:`verify_certificate_hash <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>` and :ref:`verify_certificate_spki <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_spki>` are specified, a hash matching value from either of the lists will result in the certificate being accepted.

• repeated SubjectAltNameMatcher match_typed_subject_alt_names = 15

  An optional list of Subject Alternative name matchers. If specified, Envoy will verify that the Subject Alternative Name of the presented certificate matches one of the specified matchers. The matching uses "any" semantics, that is to say, the SAN is verified if at least one matcher is matched. When a certificate has wildcard DNS SAN entries, to match a specific client, it should be configured with exact match type in the :ref:`string matcher <envoy_v3_api_msg_type.matcher.v3.StringMatcher>`. For example if the certificate has "\*.example.com" as DNS SAN entry, to allow only "api.example.com", it should be configured as shown below. .. code-block:: yaml match_typed_subject_alt_names: - san_type: DNS matcher: exact: "api.example.com" .. attention:: Subject Alternative Names are easily spoofable and verifying only them is insecure, therefore this option must be used together with :ref:`trusted_ca <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.trusted_ca>`.

• repeated type.matcher.v3.StringMatcher match_subject_alt_names = 9

  This field is deprecated in favor of :ref:`match_typed_subject_alt_names <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.match_typed_subject_alt_names>`. Note that if both this field and :ref:`match_typed_subject_alt_names <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.match_typed_subject_alt_names>` are specified, the former (deprecated field) is ignored.

• optional google.protobuf.BoolValue require_signed_certificate_timestamp = 6

  [#not-implemented-hide:] Must present signed certificate time-stamp.

• optional config.core.v3.DataSource crl = 7

  An optional `certificate revocation list <https://en.wikipedia.org/wiki/Certificate_revocation_list>`_ (in PEM format). If specified, Envoy will verify that the presented peer certificate has not been revoked by this CRL. If this DataSource contains multiple CRLs, all of them will be used. Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. This default behavior can be altered by setting :ref:`only_verify_leaf_cert_crl <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.only_verify_leaf_cert_crl>` to true. If ``crl`` is a filesystem path, a watch will be added to the parent directory for any file moves to support rotation. This currently only applies to dynamic secrets, when the ``CertificateValidationContext`` is delivered via SDS.

• bool allow_expired_certificate = 8

  If specified, Envoy will not reject expired certificates.

• CertificateValidationContext.TrustChainVerification trust_chain_verification = 10

  Certificate trust chain verification mode.

• optional config.core.v3.TypedExtensionConfig custom_validator_config = 12

  The configuration of an extension specific certificate validator. If specified, all validation is done by the specified validator, and the behavior of all other validation settings is defined by the specified validator (and may be entirely ignored, unused, and unvalidated). Refer to the documentation for the specified validator. If you do not want a custom validation algorithm, do not set this field. [#extension-category: envoy.tls.cert_validator]

• bool only_verify_leaf_cert_crl = 14

  If this option is set to true, only the certificate at the end of the certificate chain will be subject to validation by :ref:`CRL <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.crl>`.

• optional google.protobuf.UInt32Value max_verify_depth = 16

  Defines maximum depth of a certificate chain accepted in verification, the default limit is 100, though this can be system-dependent. This number does not include the leaf but includes the trust anchor, so a depth of 1 allows the leaf and one CA certificate. If a trusted issuer appears in the chain, but in a depth larger than configured, the certificate validation will fail. This matches the semantics of ``SSL_CTX_set_verify_depth`` in OpenSSL 1.0.x and older versions of BoringSSL. It differs from ``SSL_CTX_set_verify_depth`` in OpenSSL 1.1.x and newer versions of BoringSSL in that the trust anchor is included. Trusted issues are specified by setting :ref:`trusted_ca <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.trusted_ca>`

Used in: CertificateValidationContext

(message has no fields)

Peer certificate verification mode.

Used in: CertificateValidationContext

• VERIFY_TRUST_CHAIN = 0

  Perform default certificate verification (e.g., against CA / verification lists)

• ACCEPT_UNTRUSTED = 1

  Connections where the certificate fails verification will be permitted. For HTTP connections, the result of certificate verification can be used in route matching. ( see :ref:`validated <envoy_v3_api_field_config.route.v3.RouteMatch.TlsContextMatchOptions.validated>` ).

TLS context shared by both client and server TLS contexts. [#next-free-field: 17]

Used in: DownstreamTlsContext, UpstreamTlsContext

• optional TlsParameters tls_params = 1

  TLS protocol versions, cipher suites etc.

• repeated TlsCertificate tls_certificates = 2

  Only a single TLS certificate is supported in client contexts. In server contexts, :ref:`Multiple TLS certificates <arch_overview_ssl_cert_select>` 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.

• repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6

  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 :ref:`tls_certificates <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.tls_certificates>` are valid in the certificates fetched through this setting. If ``tls_certificates`` or ``tls_certificate_provider_instance`` are set, this field is ignored.

• optional CertificateProviderPluginInstance tls_certificate_provider_instance = 14

  Certificate provider instance for fetching TLS certs. If this field is set, ``tls_certificates`` and ``tls_certificate_provider_instance`` are ignored. [#not-implemented-hide:]

• optional config.core.v3.TypedExtensionConfig custom_tls_certificate_selector = 16

  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.

• optional CommonTlsContext.CertificateProvider tls_certificate_certificate_provider = 9

  Certificate provider for fetching TLS certificates. [#not-implemented-hide:]

• optional CommonTlsContext.CertificateProviderInstance tls_certificate_certificate_provider_instance = 11

  Certificate provider instance for fetching TLS certificates. [#not-implemented-hide:]

• oneof validation_context_type

  • CertificateValidationContext validation_context = 3

    How to validate peer certificates.

  • SdsSecretConfig validation_context_sds_secret_config = 7

    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.

  • CommonTlsContext.CombinedCertificateValidationContext combined_validation_context = 8

    Combines the default ``CertificateValidationContext`` with the SDS-provided dynamic context for certificate validation. When the SDS server returns a dynamic ``CertificateValidationContext``, it is merged with the default context using ``Message::MergeFrom()``. The merging rules are as follows: * **Singular Fields:** Dynamic fields override the default singular fields. * **Repeated Fields:** Dynamic repeated fields are concatenated with the default repeated fields. * **Boolean Fields:** Boolean fields are combined using a logical OR operation. The resulting ``CertificateValidationContext`` is used to perform certificate validation.

  • CommonTlsContext.CertificateProvider validation_context_certificate_provider = 10

    Certificate provider for fetching validation context. [#not-implemented-hide:]

  • CommonTlsContext.CertificateProviderInstance validation_context_certificate_provider_instance = 12

    Certificate provider instance for fetching validation context. [#not-implemented-hide:]

• repeated string alpn_protocols = 4

  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 <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.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.

• optional config.core.v3.TypedExtensionConfig custom_handshaker = 13

  Custom TLS handshaker. If empty, defaults to native TLS handshaking behavior.

• optional TlsKeyLog key_log = 15

  TLS key log configuration

Config for the Certificate Provider to fetch certificates. Certificates are fetched/refreshed asynchronously over the network relative to the TLS handshake. DEPRECATED: This message is not currently used, but if we ever do need it, we will want to move it out of CommonTlsContext and into common.proto, similar to the existing CertificateProviderPluginInstance message. [#not-implemented-hide:]

Used in: CommonTlsContext, CombinedCertificateValidationContext

• string name = 1

  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.

• oneof config

  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.

  • config.core.v3.TypedExtensionConfig typed_config = 2

Similar to CertificateProvider above, but allows the provider instances to be configured on the client side instead of being sent from the control plane. DEPRECATED: This message was moved outside of CommonTlsContext and now lives in common.proto. [#not-implemented-hide:]

Used in: CommonTlsContext, CombinedCertificateValidationContext

• string instance_name = 1

  Provider instance name. This name must be defined in the client's configuration (e.g., a bootstrap file) to correspond to a provider instance (i.e., the same data in the typed_config field that would be sent in the CertificateProvider message if the config was sent by the control plane). If not present, defaults to "default". Instance names should generally be defined not in terms of the underlying provider implementation (e.g., "file_watcher") but rather in terms of the function of the certificates (e.g., "foo_deployment_identity").

• string certificate_name = 2

  Opaque name used to specify certificate instances or types. For example, "ROOTCA" to specify a root-certificate (validation context) or "example.com" to specify a certificate for a particular domain. Not all provider instances will actually use this field, so the value defaults to the empty string.

Used in: CommonTlsContext

• optional CertificateValidationContext default_validation_context = 1

  How to validate peer certificates.

• optional SdsSecretConfig validation_context_sds_secret_config = 2

  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.

• optional CertificateProvider validation_context_certificate_provider = 3

  Certificate provider for fetching CA certs. This will populate the ``default_validation_context.trusted_ca`` field. [#not-implemented-hide:]

• optional CertificateProviderInstance validation_context_certificate_provider_instance = 4

  Certificate provider instance for fetching CA certs. This will populate the ``default_validation_context.trusted_ca`` field. [#not-implemented-hide:]

[#next-free-field: 12]

Used in: quic.v3.QuicDownstreamTransport, starttls.v3.StartTlsConfig

• optional CommonTlsContext common_tls_context = 1

  Common TLS context settings.

• optional google.protobuf.BoolValue require_client_certificate = 2

  If specified, Envoy will reject connections without a valid client certificate.

• optional google.protobuf.BoolValue require_sni = 3

  If specified, Envoy will reject connections without a valid and matching SNI. [#not-implemented-hide:]

• oneof session_ticket_keys_type

  • TlsSessionTicketKeys session_ticket_keys = 4

    TLS session ticket key settings.

  • SdsSecretConfig session_ticket_keys_sds_secret_config = 5

    Config for fetching TLS session ticket keys via SDS API.

  • bool disable_stateless_session_resumption = 7

    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 <envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.session_ticket_keys>` or :ref:`session_ticket_keys_sds_secret_config <envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.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.

• bool disable_stateful_session_resumption = 10

  If ``true``, the TLS server will not maintain a session cache of TLS sessions. .. note:: This applies only to TLSv1.2 and earlier.

• optional google.protobuf.Duration session_timeout = 6

  Maximum lifetime of TLS sessions. If specified, ``session_timeout`` will change the maximum lifetime of the TLS session. This serves as a hint for the `TLS session ticket lifetime (for TLSv1.2) <https://tools.ietf.org/html/rfc5077#section-5.6>`_. Only whole seconds are considered; fractional seconds are ignored.

• DownstreamTlsContext.OcspStaplePolicy ocsp_staple_policy = 8

  Configuration for handling certificates without an OCSP response or with expired responses. Defaults to ``LENIENT_STAPLING``

• optional google.protobuf.BoolValue full_scan_certs_on_sni_mismatch = 9

  Multiple certificates are allowed in Downstream transport socket to serve different SNI. This option controls the behavior when no matching certificate is found for the received SNI value, or no SNI value was sent. If enabled, all certificates will be evaluated for a match for non-SNI criteria such as key type and OCSP settings. If disabled, the first provided certificate will be used. Defaults to ``false``. See more details in :ref:`Multiple TLS certificates <arch_overview_ssl_cert_select>`.

• bool prefer_client_ciphers = 11

  If ``true``, the downstream client's preferred cipher is used during the handshake. If ``false``, Envoy uses its preferred cipher. .. note:: This has no effect when using TLSv1_3.

Used in: DownstreamTlsContext

• LENIENT_STAPLING = 0

  OCSP responses are optional. If absent or expired, the certificate is used without stapling.

• STRICT_STAPLING = 1

  OCSP responses are optional. If absent, the certificate is used without stapling. If present but expired, the certificate is not used for subsequent connections. Connections are rejected if no suitable certificate is found.

• MUST_STAPLE = 2

  OCSP responses are required. Connections fail if a certificate lacks a valid OCSP response. Expired responses prevent certificate use in new connections, and connections are rejected if no suitable certificate is available.

Used in: Secret

• optional config.core.v3.DataSource secret = 1

  Secret of generic type and is available to filters. It is expected that only only one of secret and secrets is set.

• map<string, config.core.v3.DataSource> secrets = 2

  For cases where multiple associated secrets need to be distributed together. It is expected that only only one of secret and secrets is set.

BoringSSL private key method configuration. The private key methods are used for external (potentially asynchronous) signing and decryption operations. Some use cases for private key methods would be TPM support and TLS acceleration.

Used in: TlsCertificate

• string provider_name = 1

  Private key method provider name. The name must match a supported private key method provider type.

• oneof config_type

  Private key method provider specific configuration.

  • google.protobuf.Any typed_config = 3

• bool fallback = 4

  If the private key provider isn't available (eg. the required hardware capability doesn't existed), Envoy will fallback to the BoringSSL default implementation when the ``fallback`` is true. The default value is ``false``.

Configuration specific to the `SPIFFE <https://github.com/spiffe/spiffe>`_ certificate validator. Example: .. validated-code-block:: yaml :type-name: envoy.extensions.transport_sockets.tls.v3.CertificateValidationContext custom_validator_config: name: envoy.tls.cert_validator.spiffe typed_config: "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.SPIFFECertValidatorConfig trust_domains: - name: foo.com trust_bundle: filename: "foo.pem" - name: envoy.com trust_bundle: filename: "envoy.pem" In this example, a presented peer certificate whose SAN matches ``spiffe://foo.com/**`` is validated against the "foo.pem" x.509 certificate. All the trust bundles are isolated from each other, so no trust domain can mint a SVID belonging to another trust domain. That means, in this example, a SVID signed by ``envoy.com``'s CA with ``spiffe://foo.com/**`` SAN would be rejected since Envoy selects the trust bundle according to the presented SAN before validate the certificate. Note that SPIFFE validator inherits and uses the following options from :ref:`CertificateValidationContext <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.CertificateValidationContext>`. - :ref:`allow_expired_certificate <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.allow_expired_certificate>` to allow expired certificates. - :ref:`match_typed_subject_alt_names <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.match_typed_subject_alt_names>` to match **URI** SAN of certificates. Unlike the default validator, SPIFFE validator only matches **URI** SAN (which equals to SVID in SPIFFE terminology) and ignore other SAN types.

• repeated SPIFFECertValidatorConfig.TrustDomain trust_domains = 1

  This field specifies trust domains used for validating incoming X.509-SVID(s).

• optional config.core.v3.DataSource trust_bundles = 2

  This field specifies all trust bundles as a single DataSource. If both trust_bundles and trust_domains are specified, trust_bundles will take precedence. Currently assumes file will be a SPIFFE Trust Bundle Map. If DataSource is a file, dynamic file watching will be enabled, and updates to the specified file will trigger a refresh of the trust_bundles.

Used in: SPIFFECertValidatorConfig

• string name = 1

  Name of the trust domain, ``example.com``, ``foo.bar.gov`` for example. Note that this must *not* have "spiffe://" prefix.

• optional config.core.v3.DataSource trust_bundle = 2

  Specify a data source holding x.509 trust bundle used for validating incoming SVID(s) in this trust domain.

Used in: filters.http.oauth2.v3.OAuth2Credentials, http.injected_credentials.generic.v3.Generic, http.injected_credentials.oauth2.v3.OAuth2.ClientCredentials, quic.connection_id_generator.quic_lb.v3.Config, CommonTlsContext, CommonTlsContext.CombinedCertificateValidationContext, DownstreamTlsContext

• string name = 1

  Name by which the secret can be uniquely referred to. When both name and config are specified, then secret can be fetched and/or reloaded via SDS. When only name is specified, then secret will be loaded from static resources.

• optional config.core.v3.ConfigSource sds_config = 2

[#next-free-field: 6]

Used in: config.bootstrap.v3.Bootstrap.StaticResources

• string name = 1

  Name (FQDN, UUID, SPKI, SHA256, etc.) by which the secret can be uniquely referred to.

• oneof type

  • TlsCertificate tls_certificate = 2

  • TlsSessionTicketKeys session_ticket_keys = 3

  • CertificateValidationContext validation_context = 4

  • GenericSecret generic_secret = 5

Matcher for subject alternative names, to match both type and value of the SAN.

Used in: rbac.principals.mtls_authenticated.v3.Config, CertificateValidationContext

• SubjectAltNameMatcher.SanType san_type = 1

  Specification of type of SAN. Note that the default enum value is an invalid choice.

• optional type.matcher.v3.StringMatcher matcher = 2

  Matcher for SAN value. If the :ref:`san_type <envoy_v3_api_field_extensions.transport_sockets.tls.v3.SubjectAltNameMatcher.san_type>` is :ref:`DNS <envoy_v3_api_enum_value_extensions.transport_sockets.tls.v3.SubjectAltNameMatcher.SanType.DNS>` and the matcher type is :ref:`exact <envoy_v3_api_field_type.matcher.v3.StringMatcher.exact>`, DNS wildcards are evaluated according to the rules in https://www.rfc-editor.org/rfc/rfc6125#section-6.4.3. For example, ``*.example.com`` would match ``test.example.com`` but not ``example.com`` and not ``a.b.example.com``. The string matching for OTHER_NAME SAN values depends on their ASN.1 type: * OBJECT: Validated against its dotted numeric notation (e.g., "1.2.3.4") * BOOLEAN: Validated against strings "true" or "false" * INTEGER/ENUMERATED: Validated against a string containing the integer value * NULL: Validated against an empty string * Other types: Validated directly against the string value

• string oid = 3

  OID Value which is required if OTHER_NAME SAN type is used. For example, UPN OID is 1.3.6.1.4.1.311.20.2.3 (Reference: http://oid-info.com/get/1.3.6.1.4.1.311.20.2.3). If set for SAN types other than OTHER_NAME, it will be ignored.

Indicates the choice of GeneralName as defined in section 4.2.1.5 of RFC 5280 to match against.

Used in: SubjectAltNameMatcher

• SAN_TYPE_UNSPECIFIED = 0

• EMAIL = 1

• DNS = 2

• URI = 3

• IP_ADDRESS = 4

• OTHER_NAME = 5

[#next-free-field: 9]

Used in: CommonTlsContext, Secret

• optional config.core.v3.DataSource certificate_chain = 1

  The TLS certificate chain. If ``certificate_chain`` is a filesystem path, a watch will be added to the parent directory for any file moves to support rotation. This currently only applies to dynamic secrets, when the ``TlsCertificate`` is delivered via SDS.

• optional config.core.v3.DataSource private_key = 2

  The TLS private key. If ``private_key`` is a filesystem path, a watch will be added to the parent directory for any file moves to support rotation. This currently only applies to dynamic secrets, when the ``TlsCertificate`` is delivered via SDS.

• optional config.core.v3.DataSource pkcs12 = 8

  ``Pkcs12`` data containing TLS certificate, chain, and private key. If ``pkcs12`` is a filesystem path, the file will be read, but no watch will be added to the parent directory, since ``pkcs12`` isn't used by SDS. This field is mutually exclusive with ``certificate_chain``, ``private_key`` and ``private_key_provider``. This can't be marked as ``oneof`` due to API compatibility reasons. Setting both :ref:`private_key <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.private_key>`, :ref:`certificate_chain <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.certificate_chain>`, or :ref:`private_key_provider <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.private_key_provider>` and :ref:`pkcs12 <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.pkcs12>` fields will result in an error. Use :ref:`password <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.password>` to specify the password to unprotect the ``PKCS12`` data, if necessary.

• optional config.core.v3.WatchedDirectory watched_directory = 7

  If specified, updates of file-based ``certificate_chain`` and ``private_key`` sources will be triggered by this watch. The certificate/key pair will be read together and validated for atomic read consistency (i.e. no intervening modification occurred between cert/key read, verified by file hash comparisons). This allows explicit control over the path watched, by default the parent directories of the filesystem paths in ``certificate_chain`` and ``private_key`` are watched if this field is not specified. This only applies when a ``TlsCertificate`` is delivered by SDS with references to filesystem paths. See the :ref:`SDS key rotation <sds_key_rotation>` documentation for further details.

• optional PrivateKeyProvider private_key_provider = 6

  BoringSSL private key method provider. This is an alternative to :ref:`private_key <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.private_key>` field. When both :ref:`private_key <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.private_key>` and :ref:`private_key_provider <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.private_key_provider>` fields are set, ``private_key_provider`` takes precedence. If ``private_key_provider`` is unavailable and :ref:`fallback <envoy_v3_api_field_extensions.transport_sockets.tls.v3.PrivateKeyProvider.fallback>` is enabled, ``private_key`` will be used.

• optional config.core.v3.DataSource password = 3

  The password to decrypt the TLS private key. If this field is not set, it is assumed that the TLS private key is not password encrypted.

• optional config.core.v3.DataSource ocsp_staple = 4

  The OCSP response to be stapled with this certificate during the handshake. The response must be DER-encoded and may only be provided via ``filename`` or ``inline_bytes``. The response may pertain to only one certificate.

• repeated config.core.v3.DataSource signed_certificate_timestamp = 5

  [#not-implemented-hide:]

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)

Used in: CommonTlsContext

• string path = 1

  Path to save the TLS key log.

• repeated config.core.v3.CidrRange local_address_range = 2

  Local IP address ranges to filter connections for TLS key logging. If not set, matches any local IP address.

• repeated config.core.v3.CidrRange remote_address_range = 3

  Remote IP address ranges to filter connections for TLS key logging. If not set, matches any remote IP address.

[#next-free-field: 7]

Used in: CommonTlsContext

• TlsParameters.TlsProtocol tls_minimum_protocol_version = 1

  Minimum TLS protocol version. By default, it's ``TLSv1_2`` for both clients and servers. TLS protocol versions below TLSv1_2 require setting compatible ciphers with the ``cipher_suites`` setting as the default ciphers no longer include compatible ciphers. .. attention:: Using TLS protocol versions below TLSv1_2 has serious security considerations and risks.

• TlsParameters.TlsProtocol tls_maximum_protocol_version = 2

  Maximum TLS protocol version. By default, it's ``TLSv1_2`` for clients and ``TLSv1_3`` for servers.

• repeated string cipher_suites = 3

  If specified, the TLS listener will only support the specified `cipher list <https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration>`_ when negotiating TLS 1.0-1.2 (this setting has no effect when negotiating TLS 1.3). If not specified, a default list will be used. Defaults are different for server (downstream) and client (upstream) TLS configurations. Defaults will change over time in response to security considerations; If you care, configure it instead of using the default. In non-FIPS builds, the default server cipher list is: .. code-block:: none [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 In builds using :ref:`BoringSSL FIPS <arch_overview_ssl_fips>`, the default server cipher list is: .. code-block:: none ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 In non-FIPS builds, the default client cipher list is: .. code-block:: none [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 In builds using :ref:`BoringSSL FIPS <arch_overview_ssl_fips>`, the default client cipher list is: .. code-block:: none ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384

• repeated string ecdh_curves = 4

  If specified, the TLS connection will only support the specified ECDH curves. If not specified, the default curves will be used. In non-FIPS builds, the default curves are: .. code-block:: none X25519 P-256 In builds using :ref:`BoringSSL FIPS <arch_overview_ssl_fips>`, the default curve is: .. code-block:: none P-256

• repeated string signature_algorithms = 5

  If specified, the TLS connection will only support the specified signature algorithms. The list is ordered by preference. If not specified, the default signature algorithms defined by BoringSSL will be used. Default signature algorithms selected by BoringSSL (may be out of date): .. code-block:: none 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 Signature algorithms supported by BoringSSL (may be out of date): .. code-block:: none 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

• repeated TlsParameters.CompliancePolicy compliance_policies = 6

  Compliance policies configure various aspects of the TLS based on the given policy. The policies are applied last during configuration and may override the other TLS parameters, or any previous policy.

Used in: TlsParameters

• FIPS_202205 = 0

  FIPS_202205 configures a TLS connection to use: * TLS 1.2 or 1.3 * For TLS 1.2, only ECDHE_[RSA|ECDSA]_WITH_AES_*_GCM_SHA*. * For TLS 1.3, only AES-GCM * P-256 or P-384 for key agreement. * For server signatures, only ``PKCS#1/PSS`` with ``SHA256/384/512``, or ECDSA with P-256 or P-384. .. attention:: Please refer to `BoringSSL policies <https://boringssl.googlesource.com/boringssl/+/refs/tags/0.20240913.0/include/openssl/ssl.h#5608>`_ for details.

Used in: TlsParameters

• TLS_AUTO = 0

  Envoy will choose the optimal TLS version.

• TLSv1_0 = 1

  TLS 1.0

• TLSv1_1 = 2

  TLS 1.1

• TLSv1_2 = 3

  TLS 1.2

• TLSv1_3 = 4

  TLS 1.3

Used in: DownstreamTlsContext, Secret

• repeated config.core.v3.DataSource keys = 1

  Keys for encrypting and decrypting TLS session tickets. The first key in the array contains the key to encrypt all new sessions created by this context. All keys are candidates for decrypting received tickets. This allows for easy rotation of keys by, for example, putting the new key first, and the previous key second. If :ref:`session_ticket_keys <envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.session_ticket_keys>` is not specified, the TLS library will still support resuming sessions via tickets, but it will use an internally-generated and managed key, so sessions cannot be resumed across hot restarts or on different hosts. Each key must contain exactly 80 bytes of cryptographically-secure random data. For example, the output of ``openssl rand 80``. .. attention:: Using this feature has serious security considerations and risks. Improper handling of keys may result in loss of secrecy in connections, even if ciphers supporting perfect forward secrecy are used. See https://www.imperialviolet.org/2013/06/27/botchingpfs.html for some discussion. To minimize the risk, you must: * Keep the session ticket keys at least as secure as your TLS certificate private keys * Rotate session ticket keys at least daily, and preferably hourly * Always generate keys using a cryptographically-secure random data source

[#next-free-field: 8]

Used in: quic.v3.QuicUpstreamTransport, starttls.v3.UpstreamStartTlsConfig

• optional CommonTlsContext common_tls_context = 1

  Common TLS context settings. .. attention:: Server certificate verification is not enabled by default. To enable verification, configure :ref:`trusted_ca<envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.trusted_ca>`.

• string sni = 2

  SNI string to use when creating TLS backend connections.

• bool auto_host_sni = 6

  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 :ref:`hostname <envoy_v3_api_field_config.endpoint.v3.Endpoint.hostname>` is set on the host. See :ref:`SNI configuration <start_quick_start_securing_sni_client>` for details on how this interacts with other validation options.

• bool auto_sni_san_validation = 7

  If true, replaces any Subject Alternative Name (SAN) validations with a validation for a DNS SAN matching the SNI value sent. The validation uses the actual requested SNI, regardless of how the SNI is configured. For common cases where an SNI value is present and the server certificate should include a corresponding SAN, this option ensures the SAN is properly validated. See the :ref:`validation configuration <start_quick_start_securing_validation>` for how this interacts with other validation options.

• bool allow_renegotiation = 3

  If true, server-initiated TLS renegotiation will be allowed. .. attention:: TLS renegotiation is considered insecure and shouldn't be used unless absolutely necessary.

• optional google.protobuf.UInt32Value max_session_keys = 4

  Maximum number of session keys (Pre-Shared Keys for TLSv1.3+, Session IDs and Session Tickets for TLSv1.2 and older) to be stored for session resumption. Defaults to 1, setting this to 0 disables session resumption.

• optional google.protobuf.BoolValue enforce_rsa_key_usage = 5

  Controls enforcement of the ``keyUsage`` extension in peer certificates. If set to ``true``, the handshake will fail if the ``keyUsage`` is incompatible with TLS usage. .. note:: The default value is ``false`` (i.e., enforcement off). It is expected to change to ``true`` in a future release. The ``ssl.was_key_usage_invalid`` in :ref:`listener metrics <config_listener_stats>` metric will be incremented for configurations that would fail if this option were enabled.