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

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
+//   <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.TlsParameters>`.
 message TlsParameters {
   enum TlsProtocol {
     // Envoy will choose the optimal TLS version.

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

@@ -80,6 +80,9 @@ message TlsParameters {
   // <https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration>`_
   // 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.

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:

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 <https://github.com/google/boringssl/blob/main/crypto/err/ssl.errordata>`_
+
+.. _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 <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.
+
+**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 <envoy_v3_api_field_extensions.transport_sockets.tls.v3.TlsParameters.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 <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.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 <config_access_log_format>` to observe the negotiated TLS group.