[SSL] Clarify TLS 1.3 cipher names (#18425)

RebeccaTamachiro · Oxyjun · web-flow · commit b5febb404af2 · 2024-11-29T14:44:43.000Z
* Fix TLS 1.3 hex values in supported-cipher-suites table

* Spell out differences in naming and fix link to RFC

* Audit and add notes for all occurrences of AEAD-

* Apply suggestion from code review

Co-authored-by: Jun Lee &lt;junlee@cloudflare.com&gt;

---------

Co-authored-by: Jun Lee &lt;junlee@cloudflare.com&gt;
diff --git a/src/content/docs/spectrum/reference/configuration-options.mdx b/src/content/docs/spectrum/reference/configuration-options.mdx
@@ -134,4 +134,4 @@ The cipher suites below are ordered based on how they appear in the ClientHello,
 | AES128-SHA                        | ✅       | ✅       | ❌       |
 | AES256-SHA                        | ✅       | ✅       | ❌       |
 
-[^1]: Although TLS 1.3 uses the same cipher suite space as previous versions of TLS, TLS 1.3 cipher suites are defined differently, only specifying the symmetric ciphers, and cannot be used for TLS 1.2. Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 1.3 (IETF TLS 1.3 draft 21). BoringSSL also hard-codes cipher preferences in this order for TLS 1.3.
+[^1]: Although TLS 1.3 uses the same cipher suite space as previous versions of TLS, TLS 1.3 cipher suites are defined differently, only specifying the symmetric ciphers, and cannot be used for TLS 1.2. Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 1.3 ([RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)). BoringSSL also hard-codes cipher preferences in this order for TLS 1.3. Refer to [TLS 1.3 cipher suites](/ssl/origin-configuration/cipher-suites/#tls-13-cipher-suites) for details.
diff --git a/src/content/docs/ssl/edge-certificates/additional-options/cipher-suites/compliance-status.mdx b/src/content/docs/ssl/edge-certificates/additional-options/cipher-suites/compliance-status.mdx
@@ -23,7 +23,7 @@ Recommended cipher suites for compliance with the [Payment Card Industry Data Se
 
 * Cipher suites:
 
-`AEAD-AES128-GCM-SHA256`, `AEAD-AES256-GCM-SHA384`, `AEAD-CHACHA20-POLY1305-SHA256`, `ECDHE-ECDSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-ECDSA-AES256-GCM-SHA384`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-ECDSA-CHACHA20-POLY1305`, `ECDHE-RSA-CHACHA20-POLY1305`
+`AEAD-AES128-GCM-SHA256`[^1], `AEAD-AES256-GCM-SHA384`[^2], `AEAD-CHACHA20-POLY1305-SHA256`[^3], `ECDHE-ECDSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-ECDSA-AES256-GCM-SHA384`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-ECDSA-CHACHA20-POLY1305`, `ECDHE-RSA-CHACHA20-POLY1305`
 
 * Formatted array to copy:
 
@@ -46,3 +46,7 @@ Recommended cipher suites for compliance with the [Federal Information Processin
 ```txt
 ["AES128-GCM-SHA256", "AES128-SHA", "AES128-SHA256", "AES256-SHA", "AES256-SHA256", "DES-CBC3-SHA", "ECDHE-ECDSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-SHA", "ECDHE-ECDSA-AES128-SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-RSA-AES128-SHA", "ECDHE-RSA-AES128-SHA256", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-SHA", "ECDHE-RSA-AES256-SHA384"]
 ```
+
+[^1]: Same as `TLS_AES_128_GCM_SHA256`. Refer to [TLS 1.3 cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/#tls-13) for details.
+[^2]: Same as `TLS_AES_256_GCM_SHA384`. Refer to [TLS 1.3 cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/#tls-13) for details.
+[^3]: Same as `TLS_CHACHA20_POLY1305_SHA256`. Refer to [TLS 1.3 cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/#tls-13) for details.
diff --git a/src/content/docs/ssl/edge-certificates/additional-options/cipher-suites/index.mdx b/src/content/docs/ssl/edge-certificates/additional-options/cipher-suites/index.mdx
@@ -20,7 +20,7 @@ This section covers cipher suites used in connections between clients -- such as
 
 Cloudflare maintains a [public repository of our SSL/TLS configurations](https://github.com/cloudflare/sslconfig) on GitHub, where you can find changes in the commit history.
 
-[RC4 cipher suites](https://blog.cloudflare.com/end-of-the-road-for-rc4/) or [SSLv3](https://blog.cloudflare.com/sslv3-support-disabled-by-default-due-to-vulnerability/) are no longer supported. 
+[RC4 cipher suites](https://blog.cloudflare.com/end-of-the-road-for-rc4/) or [SSLv3](https://blog.cloudflare.com/sslv3-support-disabled-by-default-due-to-vulnerability/) are no longer supported.
 :::
 
 ## Cipher suites and edge certificates
@@ -49,6 +49,15 @@ Each cipher suite relates to a specific minimum protocol that it supports. This
 
 <Render file="tls-13-cipher-limitations" />
 
+Cloudflare may return the following names for TLS 1.3 cipher suites. This is how they map to [RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html) names:
+
+| Cloudflare                      | RFC 8446                           |
+| ------------------------------  | -----------------------------------|
+| `AEAD-AES128-GCM-SHA256`        | `TLS_AES_128_GCM_SHA256`           |
+| `AEAD-AES256-GCM-SHA384`        | `TLS_AES_256_GCM_SHA384`           |
+| `AEAD-CHACHA20-POLY1305-SHA256` | `TLS_CHACHA20_POLY1305_SHA256`     |
+
+
 ## Resources
 
 <DirectoryListing />
diff --git a/src/content/docs/ssl/edge-certificates/additional-options/cipher-suites/recommendations.mdx b/src/content/docs/ssl/edge-certificates/additional-options/cipher-suites/recommendations.mdx
@@ -23,7 +23,7 @@ Offers the best security and performance, limiting your range of clients to mode
 
 * Cipher suites:
 
-`AEAD-AES128-GCM-SHA256`, `AEAD-AES256-GCM-SHA384`, `AEAD-CHACHA20-POLY1305-SHA256`,`ECDHE-ECDSA-AES128-GCM-SHA256`, `ECDHE-ECDSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-ECDSA-AES256-GCM-SHA384`, `ECDHE-RSA-AES256-GCM-SHA384`
+`AEAD-AES128-GCM-SHA256`[^1], `AEAD-AES256-GCM-SHA384`[^2], `AEAD-CHACHA20-POLY1305-SHA256`[^3],`ECDHE-ECDSA-AES128-GCM-SHA256`, `ECDHE-ECDSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-ECDSA-AES256-GCM-SHA384`, `ECDHE-RSA-AES256-GCM-SHA384`
 
 * Formatted array to copy:
 
@@ -58,3 +58,7 @@ Includes all cipher suites that Cloudflare supports today. Broadest compatibilit
 `AEAD-AES128-GCM-SHA256`, `AEAD-AES256-GCM-SHA384`, `AEAD-CHACHA20-POLY1305-SHA256`, `ECDHE-ECDSA-AES128-GCM-SHA256`, `ECDHE-ECDSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-ECDSA-AES256-GCM-SHA384`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-ECDSA-AES128-SHA256`, `ECDHE-RSA-AES128-SHA256`, `ECDHE-ECDSA-AES256-SHA384`, `ECDHE-RSA-AES256-SHA384`, `ECDHE-ECDSA-AES128-SHA`, `ECDHE-RSA-AES128-SHA`, `AES128-GCM-SHA256`, `AES128-SHA256`, `AES128-SHA`, `ECDHE-RSA-AES256-SHA`, `AES256-GCM-SHA384`, `AES256-SHA256`, `AES256-SHA`, `DES-CBC3-SHA`
 
 To reset your option to the default, [use an empty array](/ssl/edge-certificates/additional-options/cipher-suites/customize-cipher-suites/#reset-to-default-values).
+
+[^1]: Same as `TLS_AES_128_GCM_SHA256`. Refer to [TLS 1.3 cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/#tls-13) for details.
+[^2]: Same as `TLS_AES_256_GCM_SHA384`. Refer to [TLS 1.3 cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/#tls-13) for details.
+[^3]: Same as `TLS_CHACHA20_POLY1305_SHA256`. Refer to [TLS 1.3 cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/#tls-13) for details.
diff --git a/src/content/docs/ssl/edge-certificates/additional-options/cipher-suites/supported-cipher-suites.mdx b/src/content/docs/ssl/edge-certificates/additional-options/cipher-suites/supported-cipher-suites.mdx
@@ -33,13 +33,13 @@ Cloudflare supports the following cipher suites by default. If needed, you can [
 | AES256-SHA256                    | TLS 1.2          | Legacy                                                                   | \[0x3d]      | TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA256               |
 | AES256-SHA                       | TLS 1.0          | Legacy                                                                   | \[0x35]      | TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA                  |
 | DES-CBC3-SHA                     | TLS 1.0          | Legacy                                                                   | \[0x0a]      | TLS\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA                 |
-| AEAD-AES128-GCM-SHA256 \*        | TLS 1.3          | Modern                                                                   | {0x13,0x01}  | TLS\_AES\_128\_GCM\_SHA256                          |
-| AEAD-AES256-GCM-SHA384 \*        | TLS 1.3          | Modern                                                                   | {0x13,0x02}  | TLS\_AES\_256\_GCM\_SHA384                          |
-| AEAD-CHACHA20-POLY1305-SHA256 \* | TLS 1.3          | Modern                                                                   | {0x13,0x03}  | TLS\_CHACHA20\_POLY1305\_SHA256                     |
+| AEAD-AES128-GCM-SHA256 \*        | TLS 1.3          | Modern                                                                   | \{0x13,0x01}  | TLS\_AES\_128\_GCM\_SHA256                          |
+| AEAD-AES256-GCM-SHA384 \*        | TLS 1.3          | Modern                                                                   | \{0x13,0x02}  | TLS\_AES\_256\_GCM\_SHA384                          |
+| AEAD-CHACHA20-POLY1305-SHA256 \* | TLS 1.3          | Modern                                                                   | \{0x13,0x03}  | TLS\_CHACHA20\_POLY1305\_SHA256                     |
 
 :::note[* TLS 1.3 minimum protocol]
 
 Ciphers `AEAD-AES128-GCM-SHA256`, `AEAD-AES256-GCM-SHA384`, and `AEAD-CHACHA20-POLY1305-SHA256` are automatically supported by your zone if you [enable TLS 1.3](/ssl/edge-certificates/additional-options/tls-13/#enable-tls-13).
 
-TLS 1.3 uses the same cipher suite space as previous versions of TLS, but defines these cipher suites differently. TLS 1.3 only specifies the symmetric ciphers and cannot be used for TLS 1.2. Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 1.3 (IETF TLS 1.3 draft 21). BoringSSL also hard-codes cipher preferences in this order for TLS 1.3. 
+TLS 1.3 uses the same cipher suite space as previous versions of TLS, but defines these cipher suites differently. TLS 1.3 only specifies the symmetric ciphers and cannot be used for TLS 1.2. Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 1.3 ([RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)). BoringSSL also hard-codes cipher preferences in this order for TLS 1.3.
 :::
diff --git a/src/content/docs/ssl/origin-configuration/cipher-suites.mdx b/src/content/docs/ssl/origin-configuration/cipher-suites.mdx
@@ -38,6 +38,18 @@ The list order is based on how the cipher suites appear in the [ClientHello](htt
 | AES256-SHA                         | ✅       | ✅       | ✅       | ❌       |
 | DES-CBC3-SHA                       | ✅       | ❌       | ❌       | ❌       |
 
+### TLS 1.3 cipher suites
+
+Although TLS 1.3 uses the same cipher suite space as previous versions of TLS, TLS 1.3 cipher suites are defined differently, only specifying the symmetric ciphers, and cannot be used for TLS 1.2 ([RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)).
+
+Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 1.3. BoringSSL also hard-codes cipher preferences in the order above for TLS 1.3.
+
+Based on BoringSSL, Cloudflare system will return the names listed above. However, the corresponding names defined in [RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html) are the following:
+
+- `TLS_AES_128_GCM_SHA256`
+- `TLS_AES_256_GCM_SHA384`
+- `TLS_CHACHA20_POLY1305_SHA256`
+
 ## Match on origin
 
 Cloudflare will present the cipher suites to your origin and your server will select whichever cipher suite it prefers.
@@ -51,4 +63,4 @@ ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RS
 ssl_prefer_server_ciphers on;
 ```
 
-[^1]: *Although TLS 1.3 uses the same cipher suite space as previous versions of TLS, TLS 1.3 cipher suites are defined differently, only specifying the symmetric ciphers, and cannot be used for TLS 1.2. Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 1.3 (IETF TLS 1.3 draft 21). BoringSSL also hard-codes cipher preferences in this order for TLS 1.3.*
+[^1]: Refer to [TLS 1.3 cipher suites](#tls-13-cipher-suites) for details.
diff --git a/src/content/partials/ssl/tls-1.3-cipher-limitations.mdx b/src/content/partials/ssl/tls-1.3-cipher-limitations.mdx
@@ -3,6 +3,4 @@
 
 ---
 
-You cannot set specific TLS 1.3 ciphers. Instead, you can enable [TLS 1.3](/ssl/edge-certificates/additional-options/tls-13/#enable-tls-13) for your entire zone and Cloudflare will use [all applicable TLS 1.3 cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/supported-cipher-suites/).
-
-In combination with this, you can still [disable weak cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/customize-cipher-suites/) for TLS 1.0-1.2.
+You cannot set specific TLS 1.3 ciphers. Instead, you can enable [TLS 1.3](/ssl/edge-certificates/additional-options/tls-13/#enable-tls-13) for your entire zone and Cloudflare will use [all applicable TLS 1.3 cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/supported-cipher-suites/). In combination with this, you can still [disable weak cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/customize-cipher-suites/) for TLS 1.0-1.2.
