xds/v3/tls.proto

// Copyright 2020 The gRPC Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Local copy of Envoy xDS proto file, used for testing only.

syntax = "proto3";

package envoy.extensions.transport_sockets.tls.v3;

import "src/proto/grpc/testing/xds/v3/base.proto";
import "src/proto/grpc/testing/xds/v3/extension.proto";
import "src/proto/grpc/testing/xds/v3/string.proto";

import "google/protobuf/wrappers.proto";

// Indicates a certificate to be obtained from a named CertificateProvider plugin instance.
// The plugin instances are defined in the client's bootstrap file.
// The plugin allows certificates to be fetched/refreshed over the network asynchronously with
// respect to the TLS handshake.
// [#not-implemented-hide:]
message CertificateProviderPluginInstance {
  // Provider instance name. 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 CertificateValidationContext {
  // Certificate provider instance for fetching TLS certificates.
  //
  // Only one of *trusted_ca* and *ca_certificate_provider_instance* may be specified.
  // [#not-implemented-hide:]
  CertificateProviderPluginInstance ca_certificate_provider_instance = 13;

  // 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_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>` and
  // :ref:`verify_certificate_spki
  // <envoy_v3_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_v3_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;

  // 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_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.verify_certificate_hash>` and
  // :ref:`verify_certificate_spki
  // <envoy_v3_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;

  // An optional list of Subject Alternative name matchers. If specified, Envoy will verify that the
  // Subject Alternative Name of the presented certificate matches one of the specified matchers.
  //
  // When a certificate has wildcard DNS SAN entries, to match a specific client, it should be
  // configured with exact match type in the :ref:`string matcher <envoy_v3_api_msg_type.matcher.v3.StringMatcher>`.
  // For example if the certificate has "\*.example.com" as DNS SAN entry, to allow only "api.example.com",
  // it should be configured as shown below.
  //
  // .. code-block:: yaml
  //
  //  match_subject_alt_names:
  //    exact: "api.example.com"
  //
  // .. 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_v3_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 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. Note that if a CRL is provided
  // for any certificate authority in a trust chain, a CRL must be provided
  // for all certificate authorities in that chain. Failure to do so will
  // result in verification failure for both revoked and unrevoked certificates
  // from that chain.
  config.core.v3.DataSource crl = 7;

  // The configuration of an extension specific certificate validator.
  // If specified, all validation is done by the specified validator,
  // and the behavior of all other validation settings is defined by the specified validator (and may be entirely ignored, unused, and unvalidated).
  // Refer to the documentation for the specified validator. If you do not want a custom validation algorithm, do not set this field.
  // [#extension-category: envoy.tls.cert_validator]
  config.core.v3.TypedExtensionConfig custom_validator_config = 12;
}

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

message DownstreamTlsContext {
  enum OcspStaplePolicy {
    // OCSP responses are optional. If an OCSP response is absent
    // or expired, the associated certificate will be used for
    // connections without an OCSP staple.
    LENIENT_STAPLING = 0;

    // OCSP responses are optional. If an OCSP response is absent,
    // the associated certificate will be used without an
    // OCSP staple. If a response is provided but is expired,
    // the associated certificate will not be used for
    // subsequent connections. If no suitable certificate is found,
    // the connection is rejected.
    STRICT_STAPLING = 1;

    // OCSP responses are required. Configuration will fail if
    // a certificate is provided without an OCSP response. If a
    // response expires, the associated certificate will not be
    // used connections. If no suitable certificate is found, the
    // connection is rejected.
    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;

  // Config for whether to use certificates if they do not have
  // an accompanying OCSP response or if the response expires at runtime.
  // Defaults to LENIENT_STAPLING
  OcspStaplePolicy ocsp_staple_policy = 8;
}


// TLS context shared by both client and server TLS contexts.
// [#next-free-field: 14]
message CommonTlsContext {
  // Similar to CertificateProvider above, but allows the provider instances to be configured on
  // the client side instead of being sent from the control plane.
  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 {
    // How to validate peer certificates.
    CertificateValidationContext default_validation_context = 1;

    // Certificate provider instance for fetching validation context.
    // Only one of validation_context_sds_secret_config, validation_context_certificate_provider,
    // or validation_context_certificate_provider_instance may be used.
    CertificateProviderInstance validation_context_certificate_provider_instance = 4;
  }

  message TlsParameters {}

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

  message TlsCertificate {}

  // :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.
  //
  // Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*,
  // and *tls_certificate_provider_instance* may be used.
  // [#next-major-version: These mutually exclusive fields should ideally be in a oneof, but it's
  // not legal to put a repeated field in a oneof. In the next major version, we should rework
  // this to avoid this problem.]
  repeated TlsCertificate tls_certificates = 2;

  message SdsSecretConfig {}

  // 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 <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.tls_certificates>`
  // are valid in the the certificates fetched through this setting.
  //
  // Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*,
  // and *tls_certificate_provider_instance* may be used.
  // [#next-major-version: These mutually exclusive fields should ideally be in a oneof, but it's
  // not legal to put a repeated field in a oneof. In the next major version, we should rework
  // this to avoid this problem.]
  repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6;

  // Certificate provider instance for fetching TLS certs.
  //
  // Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*,
  // and *tls_certificate_provider_instance* may be used.
  // [#not-implemented-hide:]
  CertificateProviderPluginInstance tls_certificate_provider_instance = 14;

  // Certificate provider instance for fetching TLS certificates.
  CertificateProviderInstance tls_certificate_certificate_provider_instance = 11;

  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;

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

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