data-plane-api/envoy/api/v2/auth/cert.proto

syntax = "proto3";

package 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.
  TlsProtocol tls_minimum_protocol_version = 1 [(validate.rules).enum.defined_only = true];

  // Maximum TLS protocol version.
  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>`_.
  // If not specified, the default list:
  //
  // .. 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
  //
  // will be used.
  repeated string cipher_suites = 3;

  // If specified, the TLS connection will only support the specified ECDH
  // curves. If not specified, the default curves (X25519, P-256) will be used.
  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;

  // [#not-implemented-hide:]
  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_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.
  //
  // See :ref:`the TLS overview <arch_overview_ssl_enabling_verification>` for a list of common
  // system CA locations.
  core.DataSource trusted_ca = 1;

  // If specified, Envoy will verify (pin) the hex-encoded SHA-256 fingerprint of
  // the presented certificate.
  //
  // For example, ``openssl`` can produce a SHA-256 fingerprint of an x509 certificate
  // with the following command:
  //
  // .. code-block:: bash
  //
  //   $ openssl x509 -in path/to/client.crt -noout -fingerprint -sha256
  repeated string verify_certificate_hash = 2;

  // If specified, Envoy will verify (pin) base64-encoded SHA-256 hash of
  // the Subject Public Key Information (SPKI) of the presented certificate.
  // This is the same format as used in HTTP Public Key Pinning.
  // [#not-implemented-hide:]
  repeated string verify_spki_sha256 = 3;

  // An optional list of subject alternative names. If specified, Envoy will verify that
  // the certificate’s subject alternative name matches one of the specified values.
  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
  // <http://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;
}

// TLS context shared by both client and server TLS contexts.
message CommonTlsContext {
  // TLS protocol versions, cipher suites etc.
  TlsParameters tls_params = 1;

  // Multiple TLS certificates can be associated with the same context.
  // E.g. to allow both RSA and ECDSA certificates, two TLS certificates can be configured.
  //
  // .. attention::
  //
  //   Although this is a list, currently only a single certificate is supported. This will be
  //   relaxed in the future.
  repeated TlsCertificate tls_certificates = 2 [(validate.rules).repeated .max_items = 1];

  // [#not-implemented-hide:]
  repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6;

  // How to validate peer certificates.
  CertificateValidationContext validation_context = 3;

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

  // These fields are deprecated and only are used during the interim v1 -> v2
  // transition period for internal purposes. They should not be used outside of
  // the Envoy binary. [#not-implemented-hide:]
  message DeprecatedV1 {
    string alt_alpn_protocols = 1;
  }

  // [#not-implemented-hide:]
  DeprecatedV1 deprecated_v1 = 5 [deprecated = true];
}

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

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]
// [#not-implemented-hide:]
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]
// [#not-implemented-hide:]
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;
  }
}