envoy.extensions.transport_sockets.tls.v3.cert.proto Maven / Gradle / Ivy
syntax = "proto3";
package envoy.extensions.transport_sockets.tls.v3;
import "envoy/config/core/v3/base.proto";
import "envoy/config/core/v3/config_source.proto";
import "envoy/type/matcher/v3/string.proto";
import "google/protobuf/any.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";
import "udpa/annotations/sensitive.proto";
import "udpa/annotations/versioning.proto";
import "validate/validate.proto";
option java_package = "io.envoyproxy.envoy.extensions.transport_sockets.tls.v3";
option java_outer_classname = "CertProto";
option java_multiple_files = true;
// [#protodoc-title: Common TLS configuration]
message TlsParameters {
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 clients and ``TLSv1_0`` for
// servers.
TlsProtocol tls_minimum_protocol_version = 1 [(validate.rules).enum = {defined_only: true}];
// Maximum TLS protocol version. By default, it's ``TLSv1_3`` for servers in non-FIPS builds, and
// ``TLSv1_2`` for clients and for servers using :ref:`BoringSSL FIPS `.
TlsProtocol tls_maximum_protocol_version = 2 [(validate.rules).enum = {defined_only: true}];
// If specified, the TLS listener will only support the specified `cipher list
// `_
// when negotiating TLS 1.0-1.2 (this setting has no effect when negotiating TLS 1.3). If not
// specified, the default list will be used.
//
// In non-FIPS builds, the default 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-AES128-SHA
// ECDHE-RSA-AES128-SHA
// AES128-GCM-SHA256
// AES128-SHA
// ECDHE-ECDSA-AES256-GCM-SHA384
// ECDHE-RSA-AES256-GCM-SHA384
// ECDHE-ECDSA-AES256-SHA
// ECDHE-RSA-AES256-SHA
// AES256-GCM-SHA384
// AES256-SHA
//
// In builds using :ref:`BoringSSL FIPS `, the default cipher list is:
//
// .. code-block:: none
//
// ECDHE-ECDSA-AES128-GCM-SHA256
// ECDHE-RSA-AES128-GCM-SHA256
// ECDHE-ECDSA-AES128-SHA
// ECDHE-RSA-AES128-SHA
// AES128-GCM-SHA256
// AES128-SHA
// ECDHE-ECDSA-AES256-GCM-SHA384
// ECDHE-RSA-AES256-GCM-SHA384
// ECDHE-ECDSA-AES256-SHA
// ECDHE-RSA-AES256-SHA
// AES256-GCM-SHA384
// AES256-SHA
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 `, the default curve is:
//
// .. code-block:: none
//
// P-256
repeated string ecdh_curves = 4;
}
// 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.
message PrivateKeyProvider {
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_bytes: 1}];
// Private key method provider specific configuration.
oneof config_type {
google.protobuf.Any typed_config = 3 [(udpa.annotations.sensitive) = true];
}
}
// [#next-free-field: 7]
message TlsCertificate {
option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.TlsCertificate";
// The TLS certificate chain.
config.core.v3.DataSource certificate_chain = 1;
// The TLS private key.
config.core.v3.DataSource private_key = 2 [(udpa.annotations.sensitive) = true];
// BoringSSL private key method provider. This is an alternative to :ref:`private_key
// ` field. This can't be
// marked as ``oneof`` due to API compatibility reasons. Setting both :ref:`private_key
// ` and
// :ref:`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];
// [#not-implemented-hide:]
config.core.v3.DataSource ocsp_staple = 4;
// [#not-implemented-hide:]
repeated config.core.v3.DataSource signed_certificate_timestamp = 5;
}
message TlsSessionTicketKeys {
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 `
// 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];
}
// [#next-free-field: 11]
message CertificateValidationContext {
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 ` ).
ACCEPT_UNTRUSTED = 1;
}
reserved 4;
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
// `,
// :ref:`verify_certificate_spki
// `,
// :ref:`verify_certificate_hash
// `, or
// :ref:`match_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.
//
// See :ref:`the TLS overview ` for a list of common
// system CA locations.
config.core.v3.DataSource trusted_ca = 1;
// 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
// ` and
// :ref:`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
// `,
// 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_bytes: 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
// ` and
// :ref:`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_bytes: 64 max_bytes: 95}}}];
// An optional list of Subject Alternative name matchers. Envoy will verify that the
// Subject Alternative Name of the presented certificate matches one of the specified matches.
//
// .. attention::
//
// Subject Alternative Names are easily spoofable and verifying only them is insecure,
// therefore this option must be used together with :ref:`trusted_ca
// `.
repeated type.matcher.v3.StringMatcher match_subject_alt_names = 9;
// [#not-implemented-hide:] Must present a signed time-stamped OCSP response.
google.protobuf.BoolValue require_ocsp_staple = 5;
// [#not-implemented-hide:] Must present signed certificate time-stamp.
google.protobuf.BoolValue require_signed_certificate_timestamp = 6;
// An optional `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.
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}];
}
// TLS context shared by both client and server TLS contexts.
// [#next-free-field: 9]
message CommonTlsContext {
option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.CommonTlsContext";
message CombinedCertificateValidationContext {
option (udpa.annotations.versioning).previous_message_type =
"envoy.api.v2.auth.CommonTlsContext.CombinedCertificateValidationContext";
// How to validate peer certificates.
CertificateValidationContext default_validation_context = 1
[(validate.rules).message = {required: true}];
// Config for fetching validation context via SDS API.
SdsSecretConfig validation_context_sds_secret_config = 2
[(validate.rules).message = {required: true}];
}
reserved 5;
// TLS protocol versions, cipher suites etc.
TlsParameters tls_params = 1;
// :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.
repeated TlsCertificate tls_certificates = 2;
// Configs for fetching TLS certificates via SDS API.
repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6
[(validate.rules).repeated = {max_items: 1}];
oneof validation_context_type {
// How to validate peer certificates.
CertificateValidationContext validation_context = 3;
// Config for fetching validation context via SDS API.
SdsSecretConfig validation_context_sds_secret_config = 7;
// 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.
CombinedCertificateValidationContext combined_validation_context = 8;
}
// 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.
repeated string alpn_protocols = 4;
}
message UpstreamTlsContext {
option (udpa.annotations.versioning).previous_message_type =
"envoy.api.v2.auth.UpstreamTlsContext";
// Common TLS context settings.
//
// .. attention::
//
// Server certificate verification is not enabled by default. Configure
// :ref:`trusted_ca` to enable
// verification.
CommonTlsContext common_tls_context = 1;
// SNI string to use when creating TLS backend connections.
string sni = 2 [(validate.rules).string = {max_bytes: 255}];
// If true, server-initiated TLS renegotiation will be allowed.
//
// .. attention::
//
// TLS renegotiation is considered insecure and shouldn't be used unless absolutely necessary.
bool allow_renegotiation = 3;
// 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.
google.protobuf.UInt32Value max_session_keys = 4;
}
// [#next-free-field: 7]
message DownstreamTlsContext {
option (udpa.annotations.versioning).previous_message_type =
"envoy.api.v2.auth.DownstreamTlsContext";
// Common TLS context settings.
CommonTlsContext common_tls_context = 1;
// If specified, Envoy will reject connections without a valid client
// certificate.
google.protobuf.BoolValue require_client_certificate = 2;
// If specified, Envoy will reject connections without a valid and matching SNI.
// [#not-implemented-hide:]
google.protobuf.BoolValue require_sni = 3;
oneof session_ticket_keys_type {
// TLS session ticket key settings.
TlsSessionTicketKeys session_ticket_keys = 4;
// Config for fetching TLS session ticket keys via SDS API.
SdsSecretConfig session_ticket_keys_sds_secret_config = 5;
}
// 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).
google.protobuf.Duration session_timeout = 6 [(validate.rules).duration = {
lt {seconds: 4294967296}
gte {}
}];
}
message GenericSecret {
option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.GenericSecret";
// Secret of generic type and is available to filters.
config.core.v3.DataSource secret = 1 [(udpa.annotations.sensitive) = true];
}
message SdsSecretConfig {
option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.SdsSecretConfig";
// Name (FQDN, UUID, SPKI, SHA256, etc.) 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.
string name = 1;
config.core.v3.ConfigSource sds_config = 2;
}
// [#next-free-field: 6]
message Secret {
option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.Secret";
// Name (FQDN, UUID, SPKI, SHA256, etc.) by which the secret can be uniquely referred to.
string name = 1;
oneof type {
TlsCertificate tls_certificate = 2;
TlsSessionTicketKeys session_ticket_keys = 3;
CertificateValidationContext validation_context = 4;
GenericSecret generic_secret = 5;
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy