package envoy.api.v2.auth

Get desktop application:
View/edit binary Protocol Buffers messages

[#next-free-field: 11]

Used in: CommonTlsContext, CommonTlsContext.CombinedCertificateValidationContext, Secret

• optional core.DataSource trusted_ca = 1

  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:`match_subject_alt_names <envoy_api_field_auth.CertificateValidationContext.match_subject_alt_names>`) 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.

• repeated string verify_certificate_spki = 3

  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_hash = 2

  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_subject_alt_name = 4

  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 type.matcher.StringMatcher match_subject_alt_names = 9

  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. 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_api_msg_type.matcher.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_api_field_auth.CertificateValidationContext.trusted_ca>`.

• optional google.protobuf.BoolValue require_ocsp_staple = 5

  [#not-implemented-hide:] Must present a signed time-stamped OCSP response.

• optional google.protobuf.BoolValue require_signed_certificate_timestamp = 6

  [#not-implemented-hide:] Must present signed certificate time-stamp.

• optional core.DataSource crl = 7

  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.

• bool allow_expired_certificate = 8

  If specified, Envoy will not reject expired certificates.

• CertificateValidationContext.TrustChainVerification trust_chain_verification = 10

  Certificate trust chain verification mode.

Peer certificate verification mode.

Used in: CertificateValidationContext

• VERIFY_TRUST_CHAIN = 0

  Perform default certificate verification (e.g., against CA / verification lists)

• ACCEPT_UNTRUSTED = 1

  Connections where the certificate fails verification will be permitted. For HTTP connections, the result of certificate verification can be used in route matching. ( see :ref:`validated <envoy_api_field_route.RouteMatch.TlsContextMatchOptions.validated>` ).

TLS context shared by both client and server TLS contexts. [#next-free-field: 9]

Used in: DownstreamTlsContext, UpstreamTlsContext

• optional TlsParameters tls_params = 1

  TLS protocol versions, cipher suites etc.

• repeated TlsCertificate tls_certificates = 2

  :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 SdsSecretConfig tls_certificate_sds_secret_configs = 6

  Configs for fetching TLS certificates via SDS API.

• oneof validation_context_type

  • CertificateValidationContext validation_context = 3

    How to validate peer certificates.

  • SdsSecretConfig validation_context_sds_secret_config = 7

    Config for fetching validation context via SDS API.

  • CommonTlsContext.CombinedCertificateValidationContext combined_validation_context = 8

    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.

• repeated string alpn_protocols = 4

  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.

Used in: CommonTlsContext

• optional CertificateValidationContext default_validation_context = 1

  How to validate peer certificates.

• optional SdsSecretConfig validation_context_sds_secret_config = 2

  Config for fetching validation context via SDS API.

[#next-free-field: 8]

Used in: listener.FilterChain

• optional CommonTlsContext common_tls_context = 1

  Common TLS context settings.

• optional google.protobuf.BoolValue require_client_certificate = 2

  If specified, Envoy will reject connections without a valid client certificate.

• optional google.protobuf.BoolValue require_sni = 3

  If specified, Envoy will reject connections without a valid and matching SNI. [#not-implemented-hide:]

• oneof session_ticket_keys_type

  • TlsSessionTicketKeys session_ticket_keys = 4

    TLS session ticket key settings.

  • SdsSecretConfig session_ticket_keys_sds_secret_config = 5

    Config for fetching TLS session ticket keys via SDS API.

  • bool disable_stateless_session_resumption = 7

    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 <envoy_api_field_auth.DownstreamTlsContext.session_ticket_keys>` or :ref:`session_ticket_keys_sds_secret_config <envoy_api_field_auth.DownstreamTlsContext.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.

• optional google.protobuf.Duration session_timeout = 6

  If specified, ``session_timeout`` will change the maximum lifetime (in seconds) of the TLS session. Currently this value is used as a hint for the `TLS session ticket lifetime (for TLSv1.2) <https://tools.ietf.org/html/rfc5077#section-5.6>`_. Only seconds can be specified (fractional seconds are ignored).

Used in: Secret

• optional core.DataSource secret = 1

  Secret of generic type and is available to filters.

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.

Used in: TlsCertificate

• string provider_name = 1

  Private key method provider name. The name must match a supported private key method provider type.

• oneof config_type

  Private key method provider specific configuration.

  • google.protobuf.Struct config = 2

  • google.protobuf.Any typed_config = 3

Used in: CommonTlsContext, CommonTlsContext.CombinedCertificateValidationContext, DownstreamTlsContext

• string name = 1

  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.

• optional core.ConfigSource sds_config = 2

[#next-free-field: 6]

Used in: config.bootstrap.v2.Bootstrap.StaticResources

• string name = 1

  Name (FQDN, UUID, SPKI, SHA256, etc.) by which the secret can be uniquely referred to.

• oneof type

  • TlsCertificate tls_certificate = 2

  • TlsSessionTicketKeys session_ticket_keys = 3

  • CertificateValidationContext validation_context = 4

  • GenericSecret generic_secret = 5

[#next-free-field: 7]

Used in: CommonTlsContext, Secret

• optional core.DataSource certificate_chain = 1

  The TLS certificate chain.

• optional core.DataSource private_key = 2

  The TLS private key.

• optional PrivateKeyProvider private_key_provider = 6

  BoringSSL private key method provider. This is an alternative to :ref:`private_key <envoy_api_field_auth.TlsCertificate.private_key>` field. This can't be marked as ``oneof`` due to API compatibility reasons. Setting both :ref:`private_key <envoy_api_field_auth.TlsCertificate.private_key>` and :ref:`private_key_provider <envoy_api_field_auth.TlsCertificate.private_key_provider>` fields will result in an error.

• optional core.DataSource password = 3

  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.

• optional core.DataSource ocsp_staple = 4

  [#not-implemented-hide:]

• repeated core.DataSource signed_certificate_timestamp = 5

  [#not-implemented-hide:]

Used in: CommonTlsContext

• TlsParameters.TlsProtocol tls_minimum_protocol_version = 1

  Minimum TLS protocol version. By default, it's ``TLSv1_2`` for both clients and servers.

• TlsParameters.TlsProtocol tls_maximum_protocol_version = 2

  Maximum TLS protocol version. By default, it's ``TLSv1_2`` for clients and ``TLSv1_3`` for servers.

• repeated string cipher_suites = 3

  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 ecdh_curves = 4

  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

Used in: TlsParameters

• TLS_AUTO = 0

  Envoy will choose the optimal TLS version.

• TLSv1_0 = 1

  TLS 1.0

• TLSv1_1 = 2

  TLS 1.1

• TLSv1_2 = 3

  TLS 1.2

• TLSv1_3 = 4

  TLS 1.3

Used in: DownstreamTlsContext, Secret

• repeated core.DataSource keys = 1

  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

Used in: Cluster

• optional CommonTlsContext common_tls_context = 1

  Common TLS context settings. .. attention:: Server certificate verification is not enabled by default. Configure :ref:`trusted_ca<envoy_api_field_auth.CertificateValidationContext.trusted_ca>` to enable verification.

• string sni = 2

  SNI string to use when creating TLS backend connections.

• bool allow_renegotiation = 3

  If true, server-initiated TLS renegotiation will be allowed. .. attention:: TLS renegotiation is considered insecure and shouldn't be used unless absolutely necessary.

• optional google.protobuf.UInt32Value max_session_keys = 4

  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.