envoy.extensions.transport_sockets.tls.v3.tls.proto Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of api Show documentation
The newest version!
syntax = "proto3";

package envoy.extensions.transport_sockets.tls.v3;

import "envoy/config/core/v3/address.proto";
import "envoy/config/core/v3/extension.proto";
import "envoy/extensions/transport_sockets/tls/v3/common.proto";
import "envoy/extensions/transport_sockets/tls/v3/secret.proto";

import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";

import "envoy/annotations/deprecation.proto";
import "udpa/annotations/status.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 = "TlsProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/transport_sockets/tls/v3;tlsv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: TLS transport socket]
// [#extension: envoy.transport_sockets.tls]
// The TLS contexts below provide the transport socket configuration for upstream/downstream TLS.

// [#next-free-field: 8]
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. To enable verification, configure
  //   :ref:`trusted_ca`.
  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, replaces the SNI for the connection with the hostname of the upstream host, if
  // the hostname is known due to either a DNS cluster type or the
  // :ref:`hostname ` is set on
  // the host.
  //
  // See :ref:`SNI configuration ` for details on how this
  // interacts with other validation options.
  bool auto_host_sni = 6;

  // If true, replaces any Subject Alternative Name (SAN) validations with a validation for a DNS SAN matching
  // the SNI value sent. The validation uses the actual requested SNI, regardless of how the SNI is configured.
  //
  // For common cases where an SNI value is present and the server certificate should include a corresponding SAN,
  // this option ensures the SAN is properly validated.
  //
  // See the :ref:`validation configuration ` for how this interacts with
  // other validation options.
  bool auto_sni_san_validation = 7;

  // 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 be stored for session resumption.
  //
  // Defaults to 1, setting this to 0 disables session resumption.
  google.protobuf.UInt32Value max_session_keys = 4;

  // Controls enforcement of the ``keyUsage`` extension in peer certificates. If set to ``true``, the handshake will fail if
  // the ``keyUsage`` is incompatible with TLS usage.
  //
  // .. note::
  //   The default value is ``false`` (i.e., enforcement off). It is expected to change to ``true`` in a future release.
  //
  // The ``ssl.was_key_usage_invalid`` in :ref:`listener metrics ` metric will be incremented
  // for configurations that would fail if this option were enabled.
  google.protobuf.BoolValue enforce_rsa_key_usage = 5;
}

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

  enum OcspStaplePolicy {
    // OCSP responses are optional. If absent or expired, the certificate is used without stapling.
    LENIENT_STAPLING = 0;

    // OCSP responses are optional. If absent, the certificate is used without stapling. If present but expired,
    // the certificate is not used for subsequent connections. Connections are rejected if no suitable certificate
    // is found.
    STRICT_STAPLING = 1;

    // OCSP responses are required. Connections fail if a certificate lacks a valid OCSP response. Expired responses
    // prevent certificate use in new connections, and connections are rejected if no suitable certificate is available.
    MUST_STAPLE = 2;
  }

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

    // Config for controlling stateless TLS session resumption: setting this to true will cause the TLS
    // server to not issue TLS session tickets for the purposes of stateless TLS session resumption.
    // If set to false, the TLS server will issue TLS session tickets and encrypt/decrypt them using
    // the keys specified through either :ref:`session_ticket_keys `
    // or :ref:`session_ticket_keys_sds_secret_config `.
    // If this config is set to false and no keys are explicitly configured, the TLS server will issue
    // TLS session tickets and encrypt/decrypt them using an internally-generated and managed key, with the
    // implication that sessions cannot be resumed across hot restarts or on different hosts.
    bool disable_stateless_session_resumption = 7;
  }

  // If ``true``, the TLS server will not maintain a session cache of TLS sessions.
  //
  // .. note::
  //   This applies only to TLSv1.2 and earlier.
  //
  bool disable_stateful_session_resumption = 10;

  // Maximum lifetime of TLS sessions. If specified, ``session_timeout`` will change the maximum lifetime
  // of the TLS session.
  //
  // This serves as a hint for the `TLS session ticket lifetime (for TLSv1.2) `_.
  // Only whole seconds are considered; fractional seconds are ignored.
  google.protobuf.Duration session_timeout = 6 [(validate.rules).duration = {
    lt {seconds: 4294967296}
    gte {}
  }];

  // Configuration for handling certificates without an OCSP response or with expired responses.
  //
  // Defaults to ``LENIENT_STAPLING``
  OcspStaplePolicy ocsp_staple_policy = 8 [(validate.rules).enum = {defined_only: true}];

  // Multiple certificates are allowed in Downstream transport socket to serve different SNI.
  // This option controls the behavior when no matching certificate is found for the received SNI value,
  // or no SNI value was sent. If enabled, all certificates will be evaluated for a match for non-SNI criteria
  // such as key type and OCSP settings. If disabled, the first provided certificate will be used.
  // Defaults to ``false``. See more details in :ref:`Multiple TLS certificates `.
  google.protobuf.BoolValue full_scan_certs_on_sni_mismatch = 9;

  // If ``true``, the downstream client's preferred cipher is used during the handshake. If ``false``, Envoy
  // uses its preferred cipher.
  //
  // .. note::
  //   This has no effect when using TLSv1_3.
  //
  bool prefer_client_ciphers = 11;
}

// TLS key log configuration.
// The key log file format is "format used by NSS for its SSLKEYLOGFILE debugging output" (text taken from openssl man page)
message TlsKeyLog {
  // Path to save the TLS key log.
  string path = 1 [(validate.rules).string = {min_len: 1}];

  // Local IP address ranges to filter connections for TLS key logging. If not set, matches any local IP address.
  repeated config.core.v3.CidrRange local_address_range = 2;

  // Remote IP address ranges to filter connections for TLS key logging. If not set, matches any remote IP address.
  repeated config.core.v3.CidrRange remote_address_range = 3;
}

// TLS context shared by both client and server TLS contexts.
// [#next-free-field: 17]
message CommonTlsContext {
  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.CommonTlsContext";

  // Config for the Certificate Provider to fetch certificates. Certificates are fetched/refreshed asynchronously over
  // the network relative to the TLS handshake.
  //
  // DEPRECATED: This message is not currently used, but if we ever do need it, we will want to
  // move it out of CommonTlsContext and into common.proto, similar to the existing
  // CertificateProviderPluginInstance message.
  //
  // [#not-implemented-hide:]
  message CertificateProvider {
    // opaque name used to specify certificate instances or types. For example, "ROOTCA" to specify
    // a root-certificate (validation context) or "TLS" to specify a new tls-certificate.
    string name = 1 [(validate.rules).string = {min_len: 1}];

    // Provider specific config.
    // Note: an implementation is expected to dedup multiple instances of the same config
    // to maintain a single certificate-provider instance. The sharing can happen, for
    // example, among multiple clusters or between the tls_certificate and validation_context
    // certificate providers of a cluster.
    // This config could be supplied inline or (in future) a named xDS resource.
    oneof config {
      option (validate.required) = true;

      config.core.v3.TypedExtensionConfig typed_config = 2;
    }
  }

  // Similar to CertificateProvider above, but allows the provider instances to be configured on
  // the client side instead of being sent from the control plane.
  //
  // DEPRECATED: This message was moved outside of CommonTlsContext
  // and now lives in common.proto.
  //
  // [#not-implemented-hide:]
  message CertificateProviderInstance {
    // Provider instance name. This name must be defined in the client's configuration (e.g., a
    // bootstrap file) to correspond to a provider instance (i.e., the same data in the typed_config
    // field that would be sent in the CertificateProvider message if the config was sent by the
    // control plane). 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;
  }

  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. Note SDS API allows certificates to be
    // fetched/refreshed over the network asynchronously with respect to the TLS handshake.
    SdsSecretConfig validation_context_sds_secret_config = 2
        [(validate.rules).message = {required: true}];

    // Certificate provider for fetching CA certs. This will populate the
    // ``default_validation_context.trusted_ca`` field.
    // [#not-implemented-hide:]
    CertificateProvider validation_context_certificate_provider = 3
        [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

    // Certificate provider instance for fetching CA certs. This will populate the
    // ``default_validation_context.trusted_ca`` field.
    // [#not-implemented-hide:]
    CertificateProviderInstance validation_context_certificate_provider_instance = 4
        [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
  }

  reserved 5;

  // TLS protocol versions, cipher suites etc.
  TlsParameters tls_params = 1;

  // Only a single TLS certificate is supported in client contexts. In server contexts,
  // :ref:`Multiple TLS certificates ` can be associated with the
  // same context to allow both RSA and ECDSA certificates and support SNI-based selection.
  //
  // If ``tls_certificate_provider_instance`` is set, this field is ignored.
  // If this field is set, ``tls_certificate_sds_secret_configs`` is ignored.
  repeated TlsCertificate tls_certificates = 2;

  // Configs for fetching TLS certificates via SDS API. Note SDS API allows certificates to be
  // fetched/refreshed over the network asynchronously with respect to the TLS handshake.
  //
  // The same number and types of certificates as :ref:`tls_certificates `
  // are valid in the certificates fetched through this setting.
  //
  // If ``tls_certificates`` or ``tls_certificate_provider_instance`` are set, this field
  // is ignored.
  repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6;

  // Certificate provider instance for fetching TLS certs.
  //
  // If this field is set, ``tls_certificates`` and ``tls_certificate_provider_instance``
  // are ignored.
  // [#not-implemented-hide:]
  CertificateProviderPluginInstance tls_certificate_provider_instance = 14;

  // Custom TLS certificate selector.
  //
  // Select TLS certificate based on TLS client hello.
  // If empty, defaults to native TLS certificate selection behavior:
  // DNS SANs or Subject Common Name in TLS certificates is extracted as server name pattern to match SNI.
  config.core.v3.TypedExtensionConfig custom_tls_certificate_selector = 16;

  // Certificate provider for fetching TLS certificates.
  // [#not-implemented-hide:]
  CertificateProvider tls_certificate_certificate_provider = 9
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

  // Certificate provider instance for fetching TLS certificates.
  // [#not-implemented-hide:]
  CertificateProviderInstance tls_certificate_certificate_provider_instance = 11
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

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

    // Config for fetching validation context via SDS API. Note SDS API allows certificates to be
    // fetched/refreshed over the network asynchronously with respect to the TLS handshake.
    SdsSecretConfig validation_context_sds_secret_config = 7;

    // Combines the default ``CertificateValidationContext`` with the SDS-provided dynamic context for certificate
    // validation.
    //
    // When the SDS server returns a dynamic ``CertificateValidationContext``, it is merged
    // with the default context using ``Message::MergeFrom()``. The merging rules are as follows:
    //
    // * **Singular Fields:** Dynamic fields override the default singular fields.
    // * **Repeated Fields:** Dynamic repeated fields are concatenated with the default repeated fields.
    // * **Boolean Fields:** Boolean fields are combined using a logical OR operation.
    //
    // The resulting ``CertificateValidationContext`` is used to perform certificate validation.
    CombinedCertificateValidationContext combined_validation_context = 8;

    // Certificate provider for fetching validation context.
    // [#not-implemented-hide:]
    CertificateProvider validation_context_certificate_provider = 10
        [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

    // Certificate provider instance for fetching validation context.
    // [#not-implemented-hide:]
    CertificateProviderInstance validation_context_certificate_provider_instance = 12
        [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
  }

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

  // Custom TLS handshaker. If empty, defaults to native TLS handshaking
  // behavior.
  config.core.v3.TypedExtensionConfig custom_handshaker = 13;

  // TLS key log configuration
  TlsKeyLog key_log = 15;
}