TLS

    • Configurable ciphers: Each TLS listener and client can specify the ciphers that it supports.

    • Client certificates: Upstream/client connections can present a client certificate in addition to server certificate verification.

    • Certificate revocation: Envoy can check peer certificates against a certificate revocation list (CRL) if one is provided.

    • ALPN: TLS listeners support ALPN. The HTTP connection manager uses this information (in addition to protocol inference) to determine whether a client is speaking HTTP/1.1 or HTTP/2.

    • SNI: SNI is supported for both server (listener) and client (upstream) connections.

    • Session resumption: Server connections support resuming previous sessions via TLS session tickets (see ). Resumption can be performed across hot restarts and between parallel Envoy instances (typically useful in a front proxy configuration).

    • BoringSSL private key methods: TLS private key operations (signing and decrypting) can be performed asynchronously from an extension. This allows extending Envoy to support various key management schemes (such as TPM) and TLS acceleration. This mechanism uses .

    • OCSP Stapling: Online Certificate Stapling Protocol responses may be stapled to certificates.

    Currently Envoy is written to use BoringSSL as the TLS provider.

    FIPS 140-2

    BoringSSL can be built in a FIPS-compliant mode, following the build instructions from the , using Bazel option. Currently, this option is only available on Linux-x86_64.

    The correctness of the FIPS build can be verified by checking the presence of BoringSSL-FIPS in the --version output.

    It’s important to note that while using FIPS-compliant module is necessary for FIPS compliance, it’s not sufficient by itself, and depending on the context, additional steps might be necessary. The extra requirements may include using only approved algorithms and/or using only private keys generated by a module operating in FIPS-approved mode. For more information, please refer to the and/or an accredited CMVP laboratory.

    Please note that the FIPS-compliant build is based on an older version of BoringSSL than the non-FIPS build, and it doesn’t support the most recent QUIC APIs.

    Enabling certificate verification

    Certificate verification of both upstream and downstream connections is not enabled unless the validation context specifies one or more trusted authority certificates.

    /etc/ssl/certs/ca-certificates.crt is the default path for the system CA bundle on Debian systems. trusted_ca along with makes Envoy verify the server identity of 127.0.0.1:1234 as “foo” in the same way as e.g. cURL does on standard Debian installations. Common paths for system CA bundles on Linux and BSD are:

    • /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo etc.)

    • /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7)

    • /etc/ssl/ca-bundle.pem (OpenSUSE)

    • /usr/local/etc/ssl/cert.pem (FreeBSD)

    • /etc/ssl/cert.pem (OpenBSD)

    See the reference for UpstreamTlsContexts and for other TLS options.

    Attention

    If only trusted_ca is specified, Envoy will verify the certificate chain of the presented certificate, but not its subject name, hash, etc. Other validation context configuration is typically required depending on the deployment.

    Custom Certificate Validator

    The configuration explained above is used by the “default” certificate validator. Envoy also supports custom validators in envoy.tls.cert_validator extension category which can be configured on CertificateValidationContext.

    For example, Envoy can be configured to verify peer certificates following the specification with multiple trust bundles in a single listener or cluster. For more detail, please refer to the documentation of custom_validator_config field.

    support multiple TLS certificates. These may be a mix of RSA and P-256 ECDSA certificates. The following rules apply:

    • Only one certificate of a particular type (RSA or ECDSA) may be specified.

    • If the client supports P-256 ECDSA, a P-256 ECDSA certificate will be selected if one is present in the DownstreamTlsContext and it is in compliance with the OCSP policy.

    • If the client only supports RSA certificates, a RSA certificate will be selected if present in the .

    • Otherwise, the first certificate listed is used. This will result in a failed handshake if the client only supports RSA certificates and the server only has ECDSA certificates.

    • Static and SDS certificates may not be mixed in a given DownstreamTlsContext.

    • The selected certificate must adhere to the OCSP policy. If no such certificate is found, the connection is refused.

    Only a single TLS certificate is supported today for .

    Secret discovery service (SDS)

    TLS certificates can be specified in the static resource or can be fetched remotely. Certificate rotation is supported for static resources by sourcing or by pushing updates from the SDS server. Please see SDS for details.

    OCSP Stapling

    DownstreamTlsContexts support an ocsp_staple_policy field to control whether Envoy should stop using a certificate or continue without stapling when its associated OCSP response is missing or expired. Certificates marked as require a valid OCSP response regardless of the OCSP staple policy. In practice, a must-staple certificate causes cEnvoy to behave as if the OCSP staple policy is MUST_STAPLE. Envoy will not use a must-staple certificate for new connections after its OCSP response expires.

    OCSP responses are never stapled to TLS requests that do not indicate support for OCSP stapling via the status_request extension.

    The following runtime flags are provided to adjust the requirements of OCSP responses and override the OCSP policy. These flags default to .

    • envoy.reloadable_features.require_ocsp_response_for_must_staple_certs: Disabling this allows the operator to omit an OCSP response for must-staple certs in the config.

    • envoy.reloadable_features.check_ocsp_policy: Disabling this will disable OCSP policy checking. OCSP responses are stapled when available if the client supports it, even if the response is expired. Stapling is skipped if no response is present.

    OCSP responses are ignored for .

    Envoy provides a network filter that performs TLS client authentication via principals fetched from a REST VPN service. This filter matches the presented client certificate hash against the principal list to determine whether the connection should be allowed or not. Optional IP allowlisting can also be configured. This functionality can be used to build edge proxy VPN support for web infrastructure.

    Client TLS authentication filter configuration reference.

    Custom handshaker extension

    The CommonTlsContext has a custom_handshaker extension which can be used to override SSL handshake behavior entirely. This is useful for implementing any TLS behavior which is difficult to express with callbacks. It is not necessary to write a custom handshaker to use private key methods, see the described above.

    To avoid reimplementing all of the Ssl::ConnectionInfo interface, a custom implementation might choose to extend .

    Custom handshakers need to explicitly declare via HandshakerCapabilities which TLS features they are responsible for. The default Envoy handshaker will manage the remainder.

    A useful example handshaker, named SslHandshakerImplForTest, lives in and demonstrates special-case SSL_ERROR handling and callbacks.

    Trouble shooting

    When Envoy originates TLS when making connections to upstream clusters, any errors will be logged into field or AccessLogCommon.upstream_transport_failure_reason field. Common errors are:

    • : Envoy is still waiting SDS to deliver key/cert or root CA.

    • SSLV3_ALERT_CERTIFICATE_EXPIRED: Peer certificate is expired and not allowed in config.

    • SSLV3_ALERT_CERTIFICATE_UNKNOWN: Peer certificate is not in config specified SPKI.

    • SSLV3_ALERT_HANDSHAKE_FAILURE: Handshake failed, usually due to upstream requires client certificate but not presented.

    • TLSV1_ALERT_PROTOCOL_VERSION: TLS protocol version mismatch.

    More detailed list of error that can be raised by BoringSSL can be found