Skip to content

SSL.md

Latest commit

 

History

History
101 lines (64 loc) · 3.83 KB

SSL.md

File metadata and controls

101 lines (64 loc) · 3.83 KB

SSL library configuration

Envoy uses BoringSSL as its default SSL library. OpenSSL is also supported by the build system as an alternative SSL library.

For FIPS-compliant builds, Envoy supports both BoringSSL-FIPS and AWS-LC FIPS, which provides FIPS support for the aarch64 and ppc64le architectures.

Default (non-FIPS)

No configuration needed. Envoy builds with standard BoringSSL by default:

bazel build //source/exe:envoy-static

FIPS builds

Supported FIPS builds and architectures

At this time, only the BoringSSL FIPS build on x86_64 is supported and tested by the Envoy project.

We are happy to accept patches to allow Envoy builds with other libraries or architectures, but the responsibility for maintenance, and resolving incompatibility remains with dowstream projects.

Envoy follows the Update Stream of FIPS BoringSSL code. When an Envoy stable release branch is made, the BoringSSL FIPS version used will be compatible with the Update Stream policy, and that version (and associated build tool versions) will not be changed on the release branch unless a bug or security vulnerability which affects Envoy is reported.

BoringSSL-FIPS

bazel build --config=boringssl-fips //source/exe:envoy-static
  • Supported architectures: Linux x86_64, aarch64
  • Version string: BoringSSL-FIPS (visible in envoy --version)

AWS-LC FIPS

bazel build --config=aws-lc-fips //source/exe:envoy-static
  • Supported architectures: Linux x86_64, aarch64, ppc64le
  • Version string: AWS-LC-FIPS (visible in envoy --version)
  • Note: HTTP/3 (QUIC) is disabled for AWS-LC builds

OpenSSL

BoringSSL is the supported and default SSL implementation in Envoy. OpenSSL is offered as an alternative.

Differently from the other SSL implementations supported by Envoy, OpenSSL libraries are not statically linked into the Envoy binary. OpenSSL libraries (version 3.5 or higher) must be present at runtime. The current OpenSSL implementation will load them dynamically with dlopen().

FIPS mode in OpenSSL is enforced at runtime - not build time - through OpenSSL and/or operating system configuration.

In order to build Envoy using OpenSSL instead of BoringSSL, run:

bazel build --config=openssl //source/exe:envoy-static
  • Supported architectures: Linux x86_64, aarch64, ppc64le
  • Version string: OpenSSL (visible in envoy --version)
  • Note: HTTP/3 (QUIC) is disabled for OpenSSL builds

NOTE: Envoy builds with OpenSSL are not currently covered by Envoy Security Policy.

Migration from --define boringssl=fips

The legacy --define boringssl=fips flag no longer works. Migrate as follows:

Legacy New
--define boringssl=fips --config=boringssl-fips
--define boringssl=fips (on ppc64le) --config=aws-lc-fips

The legacy flag automatically selected AWS-LC on ppc64le. With the new approach, you must explicitly choose the library.

SSL flag integrity

The Bazel SSL configuration uses three interdependent flags: //bazel:ssl, //bazel:crypto, and //bazel:fips.

Do not set these flags directly. Use the --config options above, which ensure the flags are set consistently.

Inconsistent flag combinations (e.g., a FIPS library with --//bazel:fips=False, or mismatched ssl/crypto libraries) will produce broken builds or incorrect version strings.

Verifying FIPS build

Check the SSL library in use:

envoy --version

Look for:

  • BoringSSL-FIPS — BoringSSL FIPS build
  • AWS-LC-FIPS — AWS-LC FIPS build
  • BoringSSL — Standard (non-FIPS) build
  • OpenSSL — OpenSSL build