docs: refresh TLS defaults, TLS 1.3 cipher suites, and post-quantum key exchange documentation by Copilot · Pull Request #44944 · envoyproxy/envoy

Copilot · 2026-05-08T14:38:28Z

Envoy's TLS documentation was silent on TLS 1.3 cipher suite handling and contained no mention of post-quantum hybrid key exchange, including a non-obvious footgun: because Envoy always calls SSL_CTX_set1_curves_list with an explicit list (default X25519:P-256), BoringSSL's built-in default group list — which includes X25519MLKEM768 — is overridden, so PQ hybrid is effectively opt-in, not automatic.

Changes

api/envoy/extensions/transport_sockets/tls/v3/common.proto
- cipher_suites: added note that TLS 1.3 suites (TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256) are not configurable via this field; BoringSSL selects them.
- ecdh_curves: added warning explaining the PQ opt-in footgun, with a recommended snippet for users who want PQ hybrid:
```
ecdh_curves:
  - X25519MLKEM768
  - X25519
  - P-256
```
  Also notes that %DOWNSTREAM_TLS_GROUP% / %UPSTREAM_TLS_GROUP% can confirm whether PQ was negotiated.
api/envoy/api/v2/auth/common.proto: added a note on the frozen v2 TlsParameters message that its defaults are stale and pointing readers to the v3 message.
docs/root/intro/arch_overview/security/ssl.rst: added two new labelled sections:
- arch_overview_ssl_tls_defaults — table of default min/max TLS versions per role, TLS 1.2 and 1.3 cipher suite summary, default ECDH groups.
- arch_overview_ssl_pq_key_exchange — explains X25519MLKEM768 support, the opt-in requirement, and how to observe negotiated groups via access log formatters.
changelogs/current.yaml: added docs area entry.

No runtime defaults are changed.

Original prompt

Background

The user-facing documentation for Envoy's default TLS cipher suites, TLS protocol versions, and ECDH groups is out-of-date and incomplete. Specifically, post-quantum (PQ) hybrid key exchange (e.g. X25519MLKEM768) is not documented anywhere user-visible, and the existing proto comments only describe TLS 1.0–1.2 cipher suite defaults without explaining how TLS 1.3 cipher suites are handled. There is also a real footgun around the default value of ecdh_curves that should be called out.

This PR refreshes the documentation. It does not change runtime defaults. Any change to default behavior (e.g. adding X25519MLKEM768 to DEFAULT_CURVES) is a separate security-policy decision and is out of scope here.

Findings from investigation

api/envoy/extensions/transport_sockets/tls/v3/common.proto — TlsParameters.cipher_suites field comment (L80–L141) only documents TLS 1.0–1.2 defaults. It does not mention:
- That TLS 1.3 cipher suites are not configurable via this field and are governed by BoringSSL.
- Which TLS 1.3 cipher suites are actually negotiable (TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256).
TlsParameters.ecdh_curves in the same file — documented default is X25519:P-256 (non-FIPS) / P-256 (FIPS). This matches the constants ClientContextConfigImpl::DEFAULT_CURVES / ServerContextConfigImpl::DEFAULT_CURVES in source/common/tls/context_config_impl.cc and source/common/tls/server_context_config_impl.cc. However:
- The field doc never mentions post-quantum hybrid groups at all.
- Important: source/common/tls/context_impl.cc always calls SSL_CTX_set1_curves_list(ctx, config.ecdhCurves().c_str()) (around the line that calls SSL_CTX_set1_curves_list). Because Envoy always passes an explicit list (the default X25519:P-256), this overrides BoringSSL's built-in default group list (which would include X25519MLKEM768). The practical consequence: an Envoy non-FIPS build does not negotiate X25519MLKEM768 by default — users must explicitly configure ecdh_curves to opt in. This is a footgun and must be documented.
- The doc should give a recommended example value users can copy if they want PQ hybrid (e.g. X25519MLKEM768:X25519:P-256).
Legacy v2 API api/envoy/api/v2/auth/common.proto has stale defaults that include CBC suites (AES128-SHA, AES256-GCM-SHA384, etc.) which do not match the actual code defaults today. Since v2 is frozen, just add a note pointing readers to the v3 message.
No central doc page in docs/root/ summarises Envoy's TLS protocol/cipher/group defaults. The existing TLS arch overview at docs/root/intro/arch_overview/security/ssl.rst does not cover this. A short subsection there would help users find authoritative info quickly.
PQ-related infrastructure already exists in the repo and confirms PQ is a supported (though opt-in) capability:
- compat/openssl/source/SSL_get_curve_name.cc and the BoringSSL macro exposure in compat/openssl/patch/include/openssl/ssl.h.sh reference both SSL_GROUP_X25519_MLKEM768 and SSL_GROUP_X25519_KYBER768_DRAFT00.
- changelogs/current.yaml has a tls entry adding %DOWNSTREAM_TLS_GROUP% / %UPSTREAM_TLS_GROUP% substitution commands "to discern if a TLS connection used a post quantum safe key exchange (e.g. X25519MLKEM768)".
- PQ test certs exist under test/config/integration/certs/pqc_*.
- However, none of this is mentioned in user-facing TLS documentation.

What this PR should do

1. Update `api/envoy/extensions/transport_sockets/tls/v3/common.proto`

In the TlsParameters.cipher_suites field comment:

Keep the existing list of TLS 1.0–1.2 defaults (server/client, FIPS/non-FIPS) — they are still correct and match DEFAULT_CIPHER_SUITES / DEFAULT_CIPHER_SUITES_FIPS in source/common/tls/context_config_impl.cc and source/common/tls/server_context_config_impl.cc.
Add a clear note that this field has no effect on TLS 1.3 cipher suite selection. TLS 1.3 cipher suites are negotiated by BoringSSL and are not configurable via this field. List the TLS 1.3 cipher suites that may be negotiated:
- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256

In the TlsParameters.ecdh_curves field comment:

Keep documenting the current defaults (X25519:P-256 non-FIPS, P-256 FIPS).
Add a clearly-marked note explaining that Envoy applies this list explicitly via SSL_CTX_set1_curves_list, which overrides BoringSSL's built-in default group list. As a re...

This pull request was created from Copilot chat.

repokitteh-read-only · 2026-05-08T14:38:34Z

As a reminder, PRs marked as draft will not be automatically assigned reviewers,
or be handled by maintainer-oncall triage.

Please mark your PR as ready when you want it to be reviewed!

🐱

Caused by: #44944 was opened by Copilot.

see: more, trace.

…e 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>

ggreenway

/wait

ggreenway · 2026-05-08T15:34:58Z

  //
+  // .. note::
+  //
+  //   **TLS 1.3 cipher suites are not configurable via this field.** When TLS 1.3 is negotiated,


It says this on the previous line of docs. I don't think it needs to be stated twice in a row.

ggreenway · 2026-05-08T15:36:05Z

+  // .. 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


I think we should change the default going forward, to try to make it secure-by-default. But I don't think we should backport that behavior change; although backporting some of these doc changes to 1.38 would be useful.

ggreenway · 2026-05-08T15:37:12Z

+  // .. 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


Referencing boringssl API functions in the user facing docs isn't the appropriate level of detail for this audience. It doesn't matter why it's not enabled by default; just give an example of how to configure it so it's enabled.

ggreenway · 2026-05-08T15:38:38Z

+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


Don't reference API functions, or tell why.

Agent-Logs-Url: https://github.com/envoyproxy/envoy/sessions/ab804083-6b35-478f-93f8-472bc5d36594 Co-authored-by: phlax <454682+phlax@users.noreply.github.com>

phlax · 2026-05-08T16:32:51Z

+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**


use headings

phlax · 2026-05-08T16:33:33Z

    to discern if a TLS connection used a post quantum safe key exchange (e.g. X25519MLKEM768).

+- area: docs
+  change: |


phlax · 2026-05-08T16:33:49Z

+  //   .. code-block:: yaml
+  //
+  //     ecdh_curves:
+  //       - X25519MLKEM768


phlax · 2026-05-08T16:34:13Z


 // [#protodoc-title: Common TLS configuration]

+// .. note::


phlax · 2026-05-08T16:35:40Z

+
+TLS 1.2 cipher suites are configured via the
+:ref:`cipher_suites <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsParameters.cipher_suites>`
+field. See that field's documentation for the authoritative default list and FIPS variants.


this seems disjointed with one defined there and other here

phlax · 2026-05-08T16:36:00Z

+.. code-block:: yaml
+
+  ecdh_curves:
+    - X25519MLKEM768


Initial plan

676aa99

Copilot AI assigned Copilot and phlax May 8, 2026

Copilot started work on behalf of phlax May 8, 2026 14:38 View session

docs: refresh TLS cipher suite, TLS 1.3, and post-quantum key exchang…

a149d9f

…e 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>

Copilot AI changed the title ~~[WIP] Update Envoy TLS documentation for default cipher suites and protocols~~ docs: refresh TLS defaults, TLS 1.3 cipher suites, and post-quantum key exchange documentation May 8, 2026

Copilot finished work on behalf of phlax May 8, 2026 14:43

Copilot AI requested a review from phlax May 8, 2026 14:43

ggreenway requested changes May 8, 2026

View reviewed changes

repokitteh-read-only Bot added waiting v2-freeze labels May 8, 2026

ggreenway self-assigned this May 8, 2026

repokitteh-read-only Bot added the api label May 8, 2026

Copilot AI mentioned this pull request May 8, 2026

docs: tighten TLS 1.3 + PQ guidance and align proto/docs layering #44950

Closed

Copilot AI and others added 2 commits May 8, 2026 17:31

docs: address review feedback for TLS 1.3 and PQ guidance

00ea5c1

Agent-Logs-Url: https://github.com/envoyproxy/envoy/sessions/ab804083-6b35-478f-93f8-472bc5d36594 Co-authored-by: phlax <454682+phlax@users.noreply.github.com>

docs: normalize v2 proto note punctuation

8675ec5

Agent-Logs-Url: https://github.com/envoyproxy/envoy/sessions/ab804083-6b35-478f-93f8-472bc5d36594 Co-authored-by: phlax <454682+phlax@users.noreply.github.com>

repokitteh-read-only Bot removed the waiting label May 8, 2026

phlax reviewed May 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: refresh TLS defaults, TLS 1.3 cipher suites, and post-quantum key exchange documentation#44944

docs: refresh TLS defaults, TLS 1.3 cipher suites, and post-quantum key exchange documentation#44944
Copilot wants to merge 4 commits into
mainfrom
copilot/refresh-tls-documentation

Copilot AI commented May 8, 2026 •

edited

Loading

Uh oh!

repokitteh-read-only Bot commented May 8, 2026

Uh oh!

ggreenway left a comment

Uh oh!

ggreenway May 8, 2026

Uh oh!

ggreenway May 8, 2026

Uh oh!

ggreenway May 8, 2026

Uh oh!

ggreenway May 8, 2026

Uh oh!

phlax May 8, 2026

Uh oh!

phlax May 8, 2026

Uh oh!

phlax May 8, 2026

Uh oh!

phlax May 8, 2026

Uh oh!

phlax May 8, 2026

Uh oh!

phlax May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Background

Findings from investigation

What this PR should do

1. Update api/envoy/extensions/transport_sockets/tls/v3/common.proto

Uh oh!

repokitteh-read-only Bot commented May 8, 2026

Uh oh!

ggreenway left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented May 8, 2026 •

edited

Loading

1. Update `api/envoy/extensions/transport_sockets/tls/v3/common.proto`