option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.TlsParameters";

enum TlsProtocol {

// Envoy will choose the optimal TLS version.

TLS_AUTO = 0;

// TLS 1.0

TLSv1_0 = 1;

// TLS 1.1

TLSv1_1 = 2;

// TLS 1.2

TLSv1_2 = 3;

// TLS 1.3

TLSv1_3 = 4;

}

// 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.

TlsProtocol tls_minimum_protocol_version = 1 [(validate.rules).enum = {defined_only: true}];

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

// servers.

TlsProtocol tls_maximum_protocol_version = 2 [(validate.rules).enum = {defined_only: true}];

// 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 cipher_suites = 3;

// 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 ecdh_curves = 4;

// 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 string signature_algorithms = 5;

option (udpa.annotations.versioning).previous_message_type =

"envoy.api.v2.auth.PrivateKeyProvider";

reserved 2;

reserved "config";

// Private key method provider name. The name must match a

// supported private key method provider type.

string provider_name = 1 [(validate.rules).string = {min_len: 1}];

// Private key method provider specific configuration.

oneof config_type {

google.protobuf.Any typed_config = 3 [(udpa.annotations.sensitive) = true];

}

// 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``.

bool fallback = 4;

option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.TlsCertificate";

// 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.

config.core.v3.DataSource certificate_chain = 1;

// 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.

config.core.v3.DataSource private_key = 2 [(udpa.annotations.sensitive) = true];

// ``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.

config.core.v3.DataSource pkcs12 = 8 [(udpa.annotations.sensitive) = true];

// 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.

config.core.v3.WatchedDirectory watched_directory = 7;

// 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. 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>` and

// :ref:`private_key_provider

// <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.private_key_provider>` fields will result in an

// error.

PrivateKeyProvider private_key_provider = 6;

// 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.

config.core.v3.DataSource password = 3 [(udpa.annotations.sensitive) = true];

// 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.

config.core.v3.DataSource ocsp_staple = 4;

// [#not-implemented-hide:]

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

option (udpa.annotations.versioning).previous_message_type =

"envoy.api.v2.auth.TlsSessionTicketKeys";

// 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

repeated config.core.v3.DataSource keys = 1

[(validate.rules).repeated = {min_items: 1}, (udpa.annotations.sensitive) = true];

// Provider instance name. 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 instance_name = 1;

// 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.

string certificate_name = 2;

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

// against.

enum SanType {

SAN_TYPE_UNSPECIFIED = 0;

EMAIL = 1;

DNS = 2;

URI = 3;

IP_ADDRESS = 4;

OTHER_NAME = 5;

}

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

SanType san_type = 1 [(validate.rules).enum = {defined_only: true not_in: 0}];

// Matcher for SAN value.

//

// 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

type.matcher.v3.StringMatcher matcher = 2 [(validate.rules).message = {required: true}];

// 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.

string oid = 3;

option (udpa.annotations.versioning).previous_message_type =

"envoy.api.v2.auth.CertificateValidationContext";

// Peer certificate verification mode.

enum TrustChainVerification {

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

VERIFY_TRUST_CHAIN = 0;

// 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>` ).

ACCEPT_UNTRUSTED = 1;

}

message SystemRootCerts {

}

reserved 4, 5;

reserved "verify_subject_alt_name";

// 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``.

config.core.v3.DataSource trusted_ca = 1

[(udpa.annotations.field_migrate).oneof_promotion = "ca_cert_source"];

// Certificate provider instance for fetching TLS certificates.

//

// If set, takes precedence over ``trusted_ca``.

// [#not-implemented-hide:]

CertificateProviderPluginInstance ca_certificate_provider_instance = 13

[(udpa.annotations.field_migrate).oneof_promotion = "ca_cert_source"];

// 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:]

SystemRootCerts system_root_certs = 17;

// 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.

config.core.v3.WatchedDirectory watched_directory = 11;

// 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_spki = 3

[(validate.rules).repeated = {items {string {min_len: 44 max_bytes: 44}}}];

// 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 string verify_certificate_hash = 2

[(validate.rules).repeated = {items {string {min_len: 64 max_bytes: 95}}}];

// 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 SubjectAltNameMatcher match_typed_subject_alt_names = 15;

// 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.

repeated type.matcher.v3.StringMatcher match_subject_alt_names = 9

[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

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

google.protobuf.BoolValue require_signed_certificate_timestamp = 6;

// 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.

config.core.v3.DataSource crl = 7;

// If specified, Envoy will not reject expired certificates.

bool allow_expired_certificate = 8;

// Certificate trust chain verification mode.

TrustChainVerification trust_chain_verification = 10

[(validate.rules).enum = {defined_only: true}];

// 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]

config.core.v3.TypedExtensionConfig custom_validator_config = 12;

// 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>`.

bool only_verify_leaf_cert_crl = 14;

// 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>`

google.protobuf.UInt32Value max_verify_depth = 16 [(validate.rules).uint32 = {lte: 100}];