Common TLS configuration

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

api/v2/auth/common.proto

extensions.transport_sockets.tls.v3.TlsParameters

[extensions.transport_sockets.tls.v3.TlsParameters proto]

  1. {
  2.   "tls_minimum_protocol_version": "...",
  3.   "tls_maximum_protocol_version": "...",
  4.   "cipher_suites": [],
  5.   "ecdh_curves": []
  6. }

tls_minimum_protocol_version

(extensions.transport_sockets.tls.v3.TlsParameters.TlsProtocol) Minimum TLS protocol version. By default, it’s TLSv1_2 for clients and TLSv1_0 for servers.

tls_maximum_protocol_version

(extensions.transport_sockets.tls.v3.TlsParameters.TlsProtocol) Maximum TLS protocol version. By default, it’s TLSv1_2 for clients and TLSv1_3 for servers.

cipher_suites

(repeated string) If specified, the TLS listener will only support the specified cipher list when negotiating TLS 1.0-1.2 (this setting has no effect when negotiating TLS 1.3).

If not specified, a default list will be used. Defaults are different for server (downstream) and client (upstream) TLS configurations.

In non-FIPS builds, the default server cipher list is:

  1. [ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]
  2. [ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]
  3. ECDHE-ECDSA-AES128-SHA
  4. ECDHE-RSA-AES128-SHA
  5. AES128-GCM-SHA256
  6. AES128-SHA
  7. ECDHE-ECDSA-AES256-GCM-SHA384
  8. ECDHE-RSA-AES256-GCM-SHA384
  9. ECDHE-ECDSA-AES256-SHA
  10. ECDHE-RSA-AES256-SHA
  11. AES256-GCM-SHA384
  12. AES256-SHA

In builds using BoringSSL FIPS, the default server cipher list is:

  1. ECDHE-ECDSA-AES128-GCM-SHA256
  2. ECDHE-RSA-AES128-GCM-SHA256
  3. ECDHE-ECDSA-AES128-SHA
  4. ECDHE-RSA-AES128-SHA
  5. AES128-GCM-SHA256
  6. AES128-SHA
  7. ECDHE-ECDSA-AES256-GCM-SHA384
  8. ECDHE-RSA-AES256-GCM-SHA384
  9. ECDHE-ECDSA-AES256-SHA
  10. ECDHE-RSA-AES256-SHA
  11. AES256-GCM-SHA384
  12. AES256-SHA

In non-FIPS builds, the default client cipher list is:

  1. [ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]
  2. [ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]
  3. ECDHE-ECDSA-AES256-GCM-SHA384
  4. ECDHE-RSA-AES256-GCM-SHA384

In builds using BoringSSL FIPS, the default client cipher list is:

  1. ECDHE-ECDSA-AES128-GCM-SHA256
  2. ECDHE-RSA-AES128-GCM-SHA256
  3. ECDHE-ECDSA-AES256-GCM-SHA384
  4. ECDHE-RSA-AES256-GCM-SHA384

ecdh_curves

(repeated string) 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:

  1. X25519
  2. P-256

In builds using BoringSSL FIPS, the default curve is:

  1. P-256

Enum extensions.transport_sockets.tls.v3.TlsParameters.TlsProtocol

[extensions.transport_sockets.tls.v3.TlsParameters.TlsProtocol proto]

TLS_AUTO

(DEFAULT) ⁣Envoy will choose the optimal TLS version.

TLSv1_0

⁣TLS 1.0

TLSv1_1

⁣TLS 1.1

TLSv1_2

⁣TLS 1.2

TLSv1_3

⁣TLS 1.3

extensions.transport_sockets.tls.v3.PrivateKeyProvider

[extensions.transport_sockets.tls.v3.PrivateKeyProvider proto]

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.

  1. {
  2.   "provider_name": "...",
  3.   "typed_config": "{...}"
  4. }

provider_name

(string, REQUIRED) Private key method provider name. The name must match a supported private key method provider type.

typed_config

(Any) Private key method provider specific configuration.

extensions.transport_sockets.tls.v3.TlsCertificate

[extensions.transport_sockets.tls.v3.TlsCertificate proto]

  1. {
  2.   "certificate_chain": "{...}",
  3.   "private_key": "{...}",
  4.   "watched_directory": "{...}",
  5.   "private_key_provider": "{...}",
  6.   "password": "{...}",
  7.   "ocsp_staple": "{...}"
  8. }

certificate_chain

(config.core.v3.DataSource) The TLS certificate chain.

If certificate_chain is a filesystem path, a watch will be added to the parent directory for any file moves to support rotation. This currently only applies to dynamic secrets, when the TlsCertificate is delivered via SDS.

private_key

(config.core.v3.DataSource) The TLS private key.

If private_key is a filesystem path, a watch will be added to the parent directory for any file moves to support rotation. This currently only applies to dynamic secrets, when the TlsCertificate is delivered via SDS.

watched_directory

(config.core.v3.WatchedDirectory) If specified, updates of file-based certificate_chain and private_key sources will be triggered by this watch. The certificate/key pair will be read together and validated for atomic read consistency (i.e. no intervening modification occurred between cert/key read, verified by file hash comparisons). This allows explicit control over the path watched, by default the parent directories of the filesystem paths in certificate_chain and private_key are watched if this field is not specified. This only applies when a TlsCertificate is delivered by SDS with references to filesystem paths. See the SDS key rotation documentation for further details.

private_key_provider

(extensions.transport_sockets.tls.v3.PrivateKeyProvider) BoringSSL private key method provider. This is an alternative to private_key field. This can’t be marked as oneof due to API compatibility reasons. Setting both private_key and private_key_provider fields will result in an error.

password

(config.core.v3.DataSource) 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.

ocsp_staple

(config.core.v3.DataSource) The OCSP response to be stapled with this certificate during the handshake. The response must be DER-encoded and may only be provided via filename or inline_bytes. The response may pertain to only one certificate.

extensions.transport_sockets.tls.v3.TlsSessionTicketKeys

[extensions.transport_sockets.tls.v3.TlsSessionTicketKeys proto]

  1. {
  2.   "keys": []
  3. }

keys

(repeated config.core.v3.DataSource, REQUIRED) 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 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

extensions.transport_sockets.tls.v3.CertificateValidationContext

[extensions.transport_sockets.tls.v3.CertificateValidationContext proto]

  1. {
  2.   "trusted_ca": "{...}",
  3.   "watched_directory": "{...}",
  4.   "verify_certificate_spki": [],
  5.   "verify_certificate_hash": [],
  6.   "match_subject_alt_names": [],
  7.   "crl": "{...}",
  8.   "allow_expired_certificate": "...",
  9.   "trust_chain_verification": "...",
  10.   "custom_validator_config": "{...}"
  11. }

trusted_ca

(config.core.v3.DataSource) 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 (require_client_certificate, verify_certificate_spki, verify_certificate_hash, or 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. 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.

See the TLS overview for a list of common system CA locations.

If trusted_ca is a filesystem path, a watch will be added to the parent directory for any file moves to support rotation. This currently only applies to dynamic secrets, when the CertificateValidationContext is delivered via SDS.

Only one of trusted_ca and ca_certificate_provider_instance may be specified.

watched_directory

(config.core.v3.WatchedDirectory) If specified, updates of a file-based trusted_ca source will be triggered by this watch. This allows explicit control over the path watched, by default the parent directory of the filesystem path in trusted_ca is watched if this field is not specified. This only applies when a CertificateValidationContext is delivered by SDS with references to filesystem paths. See the SDS key rotation documentation for further details.

verify_certificate_spki

(repeated string) 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:

  1. $ openssl x509 -in path/to/client.crt -noout -pubkey
  2.   | openssl pkey -pubin -outform DER
  3.   | openssl dgst -sha256 -binary
  4.   | openssl enc -base64
  5. NvqYIYSbgK2vCJpQhObf77vv+bQWtc5ek5RIOwPiC9A=

This is the format used in HTTP Public Key Pinning.

When both: verify_certificate_hash and 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 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.

verify_certificate_hash

(repeated string) 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:

  1. $ openssl x509 -in path/to/client.crt -outform DER | openssl dgst -sha256 | cut -d" " -f2
  2. df6ff72fe9116521268f6f2dd4966f51df479883fe7037b39f75916ac3049d1a

A long hex-encoded and colon-separated SHA-256 (a.k.a. “fingerprint”) of the certificate can be generated with the following command:

  1. $ openssl x509 -in path/to/client.crt -noout -fingerprint -sha256 | cut -d"=" -f2
  2. 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: verify_certificate_hash and verify_certificate_spki are specified, a hash matching value from either of the lists will result in the certificate being accepted.

match_subject_alt_names

(repeated type.matcher.v3.StringMatcher) 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 string matcher. 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.

  1. match_subject_alt_names:
  2.   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 trusted_ca.

crl

(config.core.v3.DataSource) An optional 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.

allow_expired_certificate

(bool) If specified, Envoy will not reject expired certificates.

trust_chain_verification

(extensions.transport_sockets.tls.v3.CertificateValidationContext.TrustChainVerification) Certificate trust chain verification mode.

custom_validator_config

(config.core.v3.TypedExtensionConfig) 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.

Tip

This extension category has the following known extensions:

Enum extensions.transport_sockets.tls.v3.CertificateValidationContext.TrustChainVerification

[extensions.transport_sockets.tls.v3.CertificateValidationContext.TrustChainVerification proto]

Peer certificate verification mode.

VERIFY_TRUST_CHAIN

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

ACCEPT_UNTRUSTED

⁣Connections where the certificate fails verification will be permitted. For HTTP connections, the result of certificate verification can be used in route matching. ( see validated ).