Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
381 lines (329 sloc) 15 KB
syntax = "proto3";
package envoy.api.v2.auth;
option java_outer_classname = "CertProto";
option java_multiple_files = true;
option java_package = "io.envoyproxy.envoy.api.v2.auth";
option go_package = "auth";
import "envoy/api/v2/core/base.proto";
import "envoy/api/v2/core/config_source.proto";
import "google/protobuf/wrappers.proto";
import "validate/validate.proto";
import "gogoproto/gogo.proto";
option (gogoproto.equal_all) = true;
// [#protodoc-title: Common TLS configuration]
message 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_0``.
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 <arch_overview_ssl_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
// <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, 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 <arch_overview_ssl_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 <arch_overview_ssl_fips>`, the default curve is:
//
// .. code-block:: none
//
// P-256
repeated string ecdh_curves = 4;
}
message TlsCertificate {
// The TLS certificate chain.
core.DataSource certificate_chain = 1;
// The TLS private key.
core.DataSource private_key = 2;
// 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.
core.DataSource password = 3;
// [#not-implemented-hide:]
core.DataSource ocsp_staple = 4;
// [#not-implemented-hide:]
repeated core.DataSource signed_certificate_timestamp = 5;
}
message 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_api_field_auth.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 core.DataSource keys = 1 [(validate.rules).repeated .min_items = 1];
}
message CertificateValidationContext {
// 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_api_field_auth.DownstreamTlsContext.require_client_certificate>`,
// :ref:`verify_certificate_spki
// <envoy_api_field_auth.CertificateValidationContext.verify_certificate_spki>`,
// :ref:`verify_certificate_hash
// <envoy_api_field_auth.CertificateValidationContext.verify_certificate_hash>`, or
// :ref:`verify_subject_alt_name
// <envoy_api_field_auth.CertificateValidationContext.verify_subject_alt_name>`) 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 <arch_overview_ssl_enabling_verification>` for a list of common
// system CA locations.
core.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
// <envoy_api_field_auth.CertificateValidationContext.verify_certificate_hash>` and
// :ref:`verify_certificate_spki
// <envoy_api_field_auth.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_api_field_auth.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_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
// <envoy_api_field_auth.CertificateValidationContext.verify_certificate_hash>` and
// :ref:`verify_certificate_spki
// <envoy_api_field_auth.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_bytes: 64, max_bytes: 95}];
// An optional list of Subject Alternative Names. If specified, Envoy will verify that the
// Subject Alternative Name of the presented certificate matches one of the specified values.
//
// .. 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_api_field_auth.CertificateValidationContext.trusted_ca>`.
repeated string verify_subject_alt_name = 4;
// [#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
// <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.
core.DataSource crl = 7;
// If specified, Envoy will not reject expired certificates.
bool allow_expired_certificate = 8;
}
// TLS context shared by both client and server TLS contexts.
message CommonTlsContext {
// TLS protocol versions, cipher suites etc.
TlsParameters tls_params = 1;
// :ref:`Multiple TLS certificates <arch_overview_ssl_cert_select>` 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];
message 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];
};
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
// <envoy_api_field_config.filter.network.http_connection_manager.v2.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.
repeated string alpn_protocols = 4;
reserved 5;
}
message UpstreamTlsContext {
// Common TLS context settings.
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;
}
message 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;
// [#not-implemented-hide:]
SdsSecretConfig session_ticket_keys_sds_secret_config = 5;
}
}
// [#proto-status: experimental]
message 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 [V2-API-DIFF].
string name = 1;
core.ConfigSource sds_config = 2;
}
// [#proto-status: experimental]
message 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;
}
}
You can’t perform that action at this time.