data-plane-api/envoy/extensions/transport_sockets/tls/v3/cert.proto

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 <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;
}

// 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
  // <envoy_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_api_field_extensions.transport_sockets.tls.v3.TlsCertificate.private_key>` and
  // :ref:`private_key_provider
  // <envoy_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];

  // [#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
  // <envoy_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];
}

// [#next-free-field: 10]
message CertificateValidationContext {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.api.v2.auth.CertificateValidationContext";

  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
  // <envoy_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.require_client_certificate>`,
  // :ref:`verify_certificate_spki
  // <envoy_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_spki>`,
  // :ref:`verify_certificate_hash
  // <envoy_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>`,
  // or :ref:`verify_subject_alt_name
  // <envoy_api_field_extensions.transport_sockets.tls.v3.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.
  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
  // <envoy_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>`
  // and :ref:`verify_certificate_spki
  // <envoy_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_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_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_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>`
  // and :ref:`verify_certificate_spki
  // <envoy_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_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
  //   <envoy_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.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
  // <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.
  config.core.v3.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.
// [#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 <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}];

  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_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.
  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<envoy_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.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)
  // <https://tools.ietf.org/html/rfc5077#section-5.6>`
  // 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 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;
}

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;
  }
}