diff --git a/api/envoy/api/v2/auth/common.proto b/api/envoy/api/v2/auth/common.proto index cd55ccd4dbd63..02f160b584a8a 100644 --- a/api/envoy/api/v2/auth/common.proto +++ b/api/envoy/api/v2/auth/common.proto @@ -24,6 +24,14 @@ option (udpa.annotations.file_status).package_version_status = FROZEN; // [#protodoc-title: Common TLS configuration] +// .. note:: +// +// This message is part of the **frozen** v2 API. The default values listed here may be stale +// and do not reflect the current runtime defaults. For authoritative and up-to-date +// documentation of TLS cipher suites, ECDH curves, and protocol version defaults -- including +// TLS 1.3 cipher suite handling and post-quantum hybrid key exchange -- refer to the v3 message +// :ref:`envoy.extensions.transport_sockets.tls.v3.TlsParameters +// `. message TlsParameters { enum TlsProtocol { // Envoy will choose the optimal TLS version. diff --git a/api/envoy/extensions/transport_sockets/tls/v3/common.proto b/api/envoy/extensions/transport_sockets/tls/v3/common.proto index 9bc5fb5d02951..c121ee93319f7 100644 --- a/api/envoy/extensions/transport_sockets/tls/v3/common.proto +++ b/api/envoy/extensions/transport_sockets/tls/v3/common.proto @@ -80,6 +80,9 @@ message TlsParameters { // `_ // when negotiating TLS 1.0-1.2 (this setting has no effect when negotiating TLS 1.3). // + // For TLS 1.3 cipher suite behavior and negotiable suites, see + // :ref:`arch_overview_ssl_tls_defaults`. + // // If not specified, a default list will be used. Defaults are different for server (downstream) and // client (upstream) TLS configurations. // Defaults will change over time in response to security considerations; If you care, configure @@ -137,6 +140,26 @@ message TlsParameters { // .. code-block:: none // // P-256 + // + // .. warning:: + // + // **Post-quantum hybrid key exchange is not enabled by default.** + // + // To enable post-quantum hybrid key exchange for TLS 1.3 connections, set + // ``ecdh_curves`` explicitly, for example: + // + // .. code-block:: yaml + // + // ecdh_curves: + // - X25519MLKEM768 + // - X25519 + // - P-256 + // + // Use ``%DOWNSTREAM_TLS_GROUP%`` and ``%UPSTREAM_TLS_GROUP%`` access log formatters to + // observe the negotiated TLS group at runtime. + // + // See :ref:`arch_overview_ssl_tls_defaults` for a summary of all TLS defaults including + // post-quantum key exchange. repeated string ecdh_curves = 4; // If specified, the TLS connection will only support the specified signature algorithms. diff --git a/changelogs/current.yaml b/changelogs/current.yaml index e354271d2ed21..6bf97646029b2 100644 --- a/changelogs/current.yaml +++ b/changelogs/current.yaml @@ -163,4 +163,12 @@ new_features: Added substitution commands ``%DOWNSTREAM_TLS_GROUP%`` and ``%UPSTREAM_TLS_GROUP%``. The TLS group may be used to discern if a TLS connection used a post quantum safe key exchange (e.g. X25519MLKEM768). +- area: docs + change: | + Refreshed documentation for default TLS cipher suites, TLS 1.3 cipher suite handling, and ECDH groups. + Clarified that post-quantum hybrid key exchange is not enabled by default and can be enabled by + explicitly configuring ``ecdh_curves`` (for example with ``X25519MLKEM768``). Added a + "Post-quantum key exchange" subsection to the TLS architecture overview and updated the v3 + ``TlsParameters`` proto field comments accordingly. + deprecated: diff --git a/docs/root/intro/arch_overview/security/ssl.rst b/docs/root/intro/arch_overview/security/ssl.rst index c9e6473d5352b..89c5fa21e213a 100644 --- a/docs/root/intro/arch_overview/security/ssl.rst +++ b/docs/root/intro/arch_overview/security/ssl.rst @@ -263,3 +263,66 @@ Common errors are: More detailed list of error that can be raised by BoringSSL can be found `here `_ + +.. _arch_overview_ssl_tls_defaults: + +TLS protocol defaults, cipher suites, and groups +------------------------------------------------- + +The following summarizes Envoy's out-of-the-box TLS configuration for non-FIPS builds. FIPS builds +may differ; see :ref:`arch_overview_ssl_fips`. + +**Default TLS protocol versions** + ++------------------+---------------------+---------------------+ +| Role | Minimum version | Maximum version | ++==================+=====================+=====================+ +| Client (upstream)| TLS 1.2 | TLS 1.2 | ++------------------+---------------------+---------------------+ +| Server (downstream)| TLS 1.2 | TLS 1.3 | ++------------------+---------------------+---------------------+ + +**Default cipher suites (TLS 1.0–1.2 only)** + +TLS 1.2 cipher suites are configured via the +:ref:`cipher_suites ` +field. See that field's documentation for the authoritative default list and FIPS variants. + +**TLS 1.3 cipher suites** + +TLS 1.3 cipher suites are **not** configurable via ``cipher_suites``; BoringSSL selects from its +built-in set. The suites that may be negotiated are: + +.. code-block:: none + + TLS_AES_128_GCM_SHA256 + TLS_AES_256_GCM_SHA384 + TLS_CHACHA20_POLY1305_SHA256 + +**Default ECDH groups** + +In non-FIPS builds: ``X25519``, ``P-256``. In FIPS builds: ``P-256`` only. These are configured +via the +:ref:`ecdh_curves ` +field. + +.. _arch_overview_ssl_pq_key_exchange: + +Post-quantum key exchange +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Post-quantum hybrid key exchange is not enabled by default. + +To enable post-quantum hybrid key exchange, set ``ecdh_curves`` explicitly in +:ref:`TlsParameters `: + +.. code-block:: yaml + + ecdh_curves: + - X25519MLKEM768 + - X25519 + - P-256 + +Post-quantum hybrid groups such as ``X25519MLKEM768`` apply to TLS 1.3 connections. +Use ``%DOWNSTREAM_TLS_GROUP%`` and ``%UPSTREAM_TLS_GROUP%`` +:ref:`access log formatters ` to observe the negotiated TLS group.