From 676aa99cf24c2f63823933f4f4c410b524a16053 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 8 May 2026 14:38:27 +0000 Subject: [PATCH 1/4] Initial plan From a149d9f1bca633bee1cedfa12c50b7fbe7c59fed Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 8 May 2026 14:42:42 +0000 Subject: [PATCH 2/4] docs: refresh TLS cipher suite, TLS 1.3, and post-quantum key exchange documentation Agent-Logs-Url: https://github.com/envoyproxy/envoy/sessions/6541830a-305b-4a29-bd95-8dc0fba57ff2 Co-authored-by: phlax <454682+phlax@users.noreply.github.com> --- api/envoy/api/v2/auth/common.proto | 8 +++ .../transport_sockets/tls/v3/common.proto | 38 ++++++++++ changelogs/current.yaml | 9 +++ .../root/intro/arch_overview/security/ssl.rst | 72 +++++++++++++++++++ 4 files changed, 127 insertions(+) diff --git a/api/envoy/api/v2/auth/common.proto b/api/envoy/api/v2/auth/common.proto index cd55ccd4dbd63..f450c64b1c3d7 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..042565b16493d 100644 --- a/api/envoy/extensions/transport_sockets/tls/v3/common.proto +++ b/api/envoy/extensions/transport_sockets/tls/v3/common.proto @@ -80,6 +80,18 @@ message TlsParameters { // `_ // when negotiating TLS 1.0-1.2 (this setting has no effect when negotiating TLS 1.3). // + // .. note:: + // + // **TLS 1.3 cipher suites are not configurable via this field.** When TLS 1.3 is negotiated, + // BoringSSL selects from its built-in set of TLS 1.3 cipher suites. The suites that may be + // negotiated are: + // + // .. code-block:: none + // + // TLS_AES_128_GCM_SHA256 + // TLS_AES_256_GCM_SHA384 + // TLS_CHACHA20_POLY1305_SHA256 + // // 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 +149,32 @@ message TlsParameters { // .. code-block:: none // // P-256 + // + // .. warning:: + // + // **Post-quantum hybrid key exchange is not enabled by default.** Envoy passes the curve list + // explicitly to BoringSSL via ``SSL_CTX_set1_curves_list``, which **overrides** BoringSSL's + // built-in default group list. BoringSSL's built-in default would include the post-quantum + // hybrid group ``X25519MLKEM768``, but because Envoy always supplies an explicit list + // (defaulting to ``X25519:P-256``), ``X25519MLKEM768`` and other post-quantum hybrid groups + // are **not** negotiated unless the operator explicitly adds them to ``ecdh_curves``. + // + // Users who want post-quantum hybrid key exchange for TLS 1.3 connections should set + // ``ecdh_curves`` explicitly, for example: + // + // .. code-block:: yaml + // + // ecdh_curves: + // - X25519MLKEM768 + // - X25519 + // - P-256 + // + // Post-quantum hybrid groups only apply to TLS 1.3. Whether a given connection actually + // negotiated a post-quantum group can be observed at runtime via the + // ``%DOWNSTREAM_TLS_GROUP%`` and ``%UPSTREAM_TLS_GROUP%`` access log formatters. + // + // 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..ae7489a87dede 100644 --- a/changelogs/current.yaml +++ b/changelogs/current.yaml @@ -163,4 +163,13 @@ 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 Envoy's default ``ecdh_curves`` value (``X25519:P-256``) overrides BoringSSL's built-in + group list and therefore does not negotiate post-quantum hybrid groups such as ``X25519MLKEM768`` unless + the user explicitly configures them. Added a "Post-quantum key exchange" subsection to the TLS architecture + overview. Updated the v3 ``TlsParameters`` proto field comments accordingly and added a deprecation notice + to the frozen v2 ``TlsParameters`` message pointing to the v3 documentation. + deprecated: diff --git a/docs/root/intro/arch_overview/security/ssl.rst b/docs/root/intro/arch_overview/security/ssl.rst index c9e6473d5352b..abfabe5ed17e1 100644 --- a/docs/root/intro/arch_overview/security/ssl.rst +++ b/docs/root/intro/arch_overview/security/ssl.rst @@ -263,3 +263,75 @@ 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 +^^^^^^^^^^^^^^^^^^^^^^^^^ + +BoringSSL supports the post-quantum hybrid key exchange group ``X25519MLKEM768`` (and historically +``X25519Kyber768Draft00``) for TLS 1.3 connections. Envoy's BoringSSL integration exposes these +groups, so Envoy is **capable** of negotiating post-quantum hybrid key exchange. + +However, Envoy always passes an explicit group list to BoringSSL via +``SSL_CTX_set1_curves_list``. This **overrides** BoringSSL's built-in default group list (which +would include ``X25519MLKEM768``). Because Envoy's built-in default is ``X25519:P-256``, +post-quantum hybrid groups are **not** negotiated unless the operator explicitly opts in by +configuring ``ecdh_curves``. + +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 only apply to TLS 1.3 connections; classic groups are still +negotiated for TLS 1.2. Whether a given connection actually used a post-quantum group can be +observed at runtime via the ``%DOWNSTREAM_TLS_GROUP%`` and ``%UPSTREAM_TLS_GROUP%`` +:ref:`access log formatters `. From 00ea5c1e26a38c7417274407803b49d1928afac1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 8 May 2026 16:25:51 +0000 Subject: [PATCH 3/4] docs: address review feedback for TLS 1.3 and PQ guidance Agent-Logs-Url: https://github.com/envoyproxy/envoy/sessions/ab804083-6b35-478f-93f8-472bc5d36594 Co-authored-by: phlax <454682+phlax@users.noreply.github.com> --- .../transport_sockets/tls/v3/common.proto | 27 +++++-------------- changelogs/current.yaml | 9 +++---- .../root/intro/arch_overview/security/ssl.rst | 17 +++--------- 3 files changed, 14 insertions(+), 39 deletions(-) diff --git a/api/envoy/extensions/transport_sockets/tls/v3/common.proto b/api/envoy/extensions/transport_sockets/tls/v3/common.proto index 042565b16493d..c121ee93319f7 100644 --- a/api/envoy/extensions/transport_sockets/tls/v3/common.proto +++ b/api/envoy/extensions/transport_sockets/tls/v3/common.proto @@ -80,17 +80,8 @@ message TlsParameters { // `_ // when negotiating TLS 1.0-1.2 (this setting has no effect when negotiating TLS 1.3). // - // .. note:: - // - // **TLS 1.3 cipher suites are not configurable via this field.** When TLS 1.3 is negotiated, - // BoringSSL selects from its built-in set of TLS 1.3 cipher suites. The suites that may be - // negotiated are: - // - // .. code-block:: none - // - // TLS_AES_128_GCM_SHA256 - // TLS_AES_256_GCM_SHA384 - // TLS_CHACHA20_POLY1305_SHA256 + // 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. @@ -152,14 +143,9 @@ message TlsParameters { // // .. warning:: // - // **Post-quantum hybrid key exchange is not enabled by default.** Envoy passes the curve list - // explicitly to BoringSSL via ``SSL_CTX_set1_curves_list``, which **overrides** BoringSSL's - // built-in default group list. BoringSSL's built-in default would include the post-quantum - // hybrid group ``X25519MLKEM768``, but because Envoy always supplies an explicit list - // (defaulting to ``X25519:P-256``), ``X25519MLKEM768`` and other post-quantum hybrid groups - // are **not** negotiated unless the operator explicitly adds them to ``ecdh_curves``. + // **Post-quantum hybrid key exchange is not enabled by default.** // - // Users who want post-quantum hybrid key exchange for TLS 1.3 connections should set + // To enable post-quantum hybrid key exchange for TLS 1.3 connections, set // ``ecdh_curves`` explicitly, for example: // // .. code-block:: yaml @@ -169,9 +155,8 @@ message TlsParameters { // - X25519 // - P-256 // - // Post-quantum hybrid groups only apply to TLS 1.3. Whether a given connection actually - // negotiated a post-quantum group can be observed at runtime via the - // ``%DOWNSTREAM_TLS_GROUP%`` and ``%UPSTREAM_TLS_GROUP%`` access log formatters. + // 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. diff --git a/changelogs/current.yaml b/changelogs/current.yaml index ae7489a87dede..6bf97646029b2 100644 --- a/changelogs/current.yaml +++ b/changelogs/current.yaml @@ -166,10 +166,9 @@ new_features: - area: docs change: | Refreshed documentation for default TLS cipher suites, TLS 1.3 cipher suite handling, and ECDH groups. - Clarified that Envoy's default ``ecdh_curves`` value (``X25519:P-256``) overrides BoringSSL's built-in - group list and therefore does not negotiate post-quantum hybrid groups such as ``X25519MLKEM768`` unless - the user explicitly configures them. Added a "Post-quantum key exchange" subsection to the TLS architecture - overview. Updated the v3 ``TlsParameters`` proto field comments accordingly and added a deprecation notice - to the frozen v2 ``TlsParameters`` message pointing to the v3 documentation. + 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 abfabe5ed17e1..89c5fa21e213a 100644 --- a/docs/root/intro/arch_overview/security/ssl.rst +++ b/docs/root/intro/arch_overview/security/ssl.rst @@ -311,15 +311,7 @@ field. Post-quantum key exchange ^^^^^^^^^^^^^^^^^^^^^^^^^ -BoringSSL supports the post-quantum hybrid key exchange group ``X25519MLKEM768`` (and historically -``X25519Kyber768Draft00``) for TLS 1.3 connections. Envoy's BoringSSL integration exposes these -groups, so Envoy is **capable** of negotiating post-quantum hybrid key exchange. - -However, Envoy always passes an explicit group list to BoringSSL via -``SSL_CTX_set1_curves_list``. This **overrides** BoringSSL's built-in default group list (which -would include ``X25519MLKEM768``). Because Envoy's built-in default is ``X25519:P-256``, -post-quantum hybrid groups are **not** negotiated unless the operator explicitly opts in by -configuring ``ecdh_curves``. +Post-quantum hybrid key exchange is not enabled by default. To enable post-quantum hybrid key exchange, set ``ecdh_curves`` explicitly in :ref:`TlsParameters `: @@ -331,7 +323,6 @@ To enable post-quantum hybrid key exchange, set ``ecdh_curves`` explicitly in - X25519 - P-256 -Post-quantum hybrid groups only apply to TLS 1.3 connections; classic groups are still -negotiated for TLS 1.2. Whether a given connection actually used a post-quantum group can be -observed at runtime via the ``%DOWNSTREAM_TLS_GROUP%`` and ``%UPSTREAM_TLS_GROUP%`` -:ref:`access log formatters `. +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. From 8675ec5f455601ec932106a171b17a44c8b462aa Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 8 May 2026 16:26:33 +0000 Subject: [PATCH 4/4] docs: normalize v2 proto note punctuation Agent-Logs-Url: https://github.com/envoyproxy/envoy/sessions/ab804083-6b35-478f-93f8-472bc5d36594 Co-authored-by: phlax <454682+phlax@users.noreply.github.com> --- api/envoy/api/v2/auth/common.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/envoy/api/v2/auth/common.proto b/api/envoy/api/v2/auth/common.proto index f450c64b1c3d7..02f160b584a8a 100644 --- a/api/envoy/api/v2/auth/common.proto +++ b/api/envoy/api/v2/auth/common.proto @@ -29,7 +29,7 @@ option (udpa.annotations.file_status).package_version_status = FROZEN; // 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 +// 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 {