[SSL] Bring in PQC content to Dev Docs (#18165)

* Add placeholders for new folder and pages and fill in frontmatter

* Add outline for index.mdx and fill in TLS background info

* Apply suggestion: Reword intro to TLS building blocks

Co-authored-by: Peter Wu <[email protected]>

* Fix typo and reword index.mdx meta description

* Improve parallelism, refine text, and link out to TLS handshake LC

* Fill in hybrid key agreement section

* Complete visitor-to-cloudflare intro paragraph

* Add mermaid digram for connections and reword #2

* Fix Internet capitalization

Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>

* Rename file, fill in, and link to pqc-support

* Fix capitalization and fill in Intenal connections section

* Fill in Cf to origin and review titles and headings

* Fix missing hyphen and touch up pqc-to-origin description

* Add split ClientHello and HRR workaround to pqc-to-origin

* Add setup instructions to pqc-to-origin

* Apply suggestion from code review

Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Luke Valenta <[email protected]>
Co-authored-by: Suleman Ahmad <[email protected]>

* Replace store by harvest, adjust RFC link cf Style Guide, and split long paragarph

* Add reference to PQ signatures and link out to blog

* Fix origin server section to use fork and bssl for both cases

* Add link to Cloudflare Radar

Co-authored-by: Luke Valenta <[email protected]>

* Text review and move link to Radar higher up in the page

* Simplify origin server instructions to use BoringSSL instead of fork

Co-authored-by: Suleman Ahmad <[email protected]>

* Overall text review and remove previous origin instructions

* Apply suggestion from code review

Co-authored-by: Jun Lee <[email protected]>

---------

Co-authored-by: Peter Wu <[email protected]>
Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>
Co-authored-by: Luke Valenta <[email protected]>
Co-authored-by: Suleman Ahmad <[email protected]>
Co-authored-by: Jun Lee <[email protected]>

Author: 6 people

src/content/docs/ssl/post-quantum-cryptography/index.mdx

@@ -0,0 +1,88 @@
+---
+pcx_content_type: concept
+title: Post-quantum cryptography (PQC)
+sidebar:
+  order: 9
+  label: About PQC
+  group:
+    label: Post-quantum
+head: []
+description: Get an overview of how Cloudflare is deploying post-quantum cryptography to protect you against harvest now, decrypt later.
+---
+
+Post-quantum cryptography (PQC) refers to cryptographic algorithms that have been designed to resist attacks from [quantum computers](https://www.cloudflare.com/learning/ssl/quantum/what-is-quantum-computing/). Cloudflare has been researching and [writing about post-quantum](https://blog.cloudflare.com/tag/post-quantum/) since 2017.
+
+To protect you against the risk of [harvest now, decrypt later](https://en.wikipedia.org/wiki/Harvest_now,_decrypt_later), and considering all the [connections](#three-connections-in-the-life-of-a-request) that take place when your website or application is on Cloudflare, we have deployed and are actively expanding the use of [post-quantum hybrid key agreement](#hybrid-key-agreement).
+
+Refer to [Cloudflare Radar](https://radar.cloudflare.com/adoption-and-usage#post-quantum-encryption-adoption) for current statistics on the adoption of PQ encryption in requests to Cloudflare.
+
+:::caution[TLS 1.3]
+Cloudflare post-quantum key agreements are only supported in protocols based on TLS 1.3 (including HTTP/3) and are disabled for websites in [FIPS mode](/cloudflare-one/policies/gateway/http-policies/tls-decryption/#fips-compliance).
+:::
+
+## Three building blocks of TLS
+
+Before TLS can protect your communications, three cryptographic algorithms have to be agreed on during the [TLS handshake](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake/):
+
+- **Symmetric ciphers:** Algorithms used to encrypt and decrypt data, ensuring confidentiality and integrity (such as `CHACHA20-POLY1305`).
+- **Key agreement:** A cryptographic protocol that allows client and server to safely agree on a shared key (such as `ECDH`).
+- **Signature algorithms:** Cryptographic algorithms used to generate the digital signatures in TLS certificates (such as `RSA` and `ECDSA`).
+
+As explained in our [blog post](https://blog.cloudflare.com/pq-2024/#two-migrations), symmetric ciphers are already post-quantum secure, which means there are two migrations left to occur.
+
+### Hybrid key agreement
+
+With TLS 1.3, [X25519](https://en.wikipedia.org/wiki/Curve25519) - an Elliptic Curve Diffie-Hellman (ECDH) protocol - is the most commonly used algorithm in key agreement. However, its security can be easily broken by quantum computers using [Shor's algorithm](https://en.wikipedia.org/wiki/Shor%27s_algorithm).
+
+It is urgent to migrate key agreement to post-quantum algorithms as soon as possible. The objective is to protect against an adversary capable of harvesting today's encrypted communications and storing it until some time in the future when they can gain access to a sufficiently powerful quantum computer to decrypt it.
+
+In response to this, Cloudflare is an early adopter of ML-KEM, the post-quantum key agreement selected by the US National Institute of Standards and Technology (NIST). For a detailed timeline and more background information refer to [The state of the post-quantum Internet](https://blog.cloudflare.com/pq-2024/).
+
+Cloudflare has deployed the following hybrid key agreements:
+
+- [X25519MLKEM768](https://datatracker.ietf.org/doc/draft-kwiatkowski-tls-ecdhe-mlkem/) (Recommended)
+    - TLS identifier: `0x11ec`
+- [X25519Kyber768Draft00](https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/) (Obsolete)
+    - TLS identifier: `0x6399`
+
+A hybrid key agreement lays the groundwork as more and more [clients](#1-visitor-to-cloudflare) adopt post-quantum cryptography, while also maintaining the current security provided by X25519. It is a safer path in case of an unexpected breakthrough that renders all variants of ML-KEM insecure.
+
+### Post-quantum signatures
+
+The migration to post-quantum signatures is less urgent and more involved. Cloudflare is closely following the developments of new standards, testing their performance, and working together with browsers to understand user impact.
+
+For details refer to [A look at the latest post-quantum signature standardization candidates](https://blog.cloudflare.com/another-look-at-pq-signatures/).
+
+## Three connections in the life of a request
+
+```mermaid
+flowchart LR
+        accTitle: Three connections - from visitor to Cloudflare to origin server
+        accDescr: Diagram showing connections for an uncached request.
+        A[Visitor]
+        subgraph Cloudflare
+        X[(Cloudflare <br />service A)]
+				B[(Cloudflare <br />service B)]
+        end
+        C[(Origin server)]
+
+        A --1--> X
+				X --2--> B
+        B --3--> C
+```
+
+### 1. Visitor to Cloudflare
+
+As of [October 2022](https://blog.cloudflare.com/post-quantum-for-all/), all websites and APIs served through Cloudflare over TLS 1.3 support post-quantum hybrid key agreement. However, the connection is only post-quantum secured if the client also supports PQC.
+
+Refer to [Post-quantum cryptography support](/ssl/post-quantum-cryptography/pqc-support/) for a list of browsers and other clients that are compatible with hybrid key agreements.
+
+### 2. Internal connections
+
+As announced in [September 2023](https://blog.cloudflare.com/post-quantum-cryptography-ga/), most internal connections for Cloudflare's products and systems have been upgraded to use PQC.
+
+### 3. Cloudflare to your origin
+
+Finally, Cloudflare also supports [hybrid key agreements](#hybrid-key-agreement) when connecting to origins. In this case, post-quantum secured connections will depend on the origin servers also supporting PQC.
+
+Refer to [Post-quantum cryptography between Cloudflare and origin servers](/ssl/post-quantum-cryptography/pqc-to-origin/) for details.

src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx

@@ -0,0 +1,36 @@
+---
+pcx_content_type: reference
+title: PQC support
+sidebar:
+  order: 2
+head: []
+description: Consider information about post-quantum cryptography at Cloudflare - deployed key agreements and software support.
+---
+
+Cloudflare's deployment of post-quantum [hybrid key agreements](/ssl/post-quantum-cryptography/#hybrid-key-agreement) is supported by different software as listed below.
+
+## X25519MLKEM768
+- Default for [Firefox 132+](https://www.mozilla.org/firefox/channel/desktop/) (Beta)
+- Default for [Chrome 131+](https://www.google.com/chrome/beta/) (Beta)
+- Cloudflare's [fork of Go](https://github.com/cloudflare/go)
+- [BoringSSL](https://boringssl.googlesource.com/boringssl/)
+
+## X25519Kyber768Draft00
+
+- Default for [Chrome 124-130](https://www.google.com/chrome/) on Desktop
+    - For older Chrome or on mobile, toggle _TLS 1.3 hybridized Kyber support_ (`enable-tls13-kyber`) in `chrome://flags`.
+- Default for [Edge 124+](https://microsoft.com/edge/)
+- Default for recent [Opera](https://opera.com) and [Brave](https://brave.com)
+- [Firefox 124+](https://www.mozilla.org/firefox) if you turn on `security.tls.enable_kyber` in `about:config`
+    - For QUIC/HTTP3, use Firefox 128+ with `network.http.http3.enable_kyber`.
+- Cloudflare's [fork of Go](https://github.com/cloudflare/go)
+- Default for [Go 1.23](https://github.com/golang/go/issues/67061)
+- [BoringSSL](https://boringssl.googlesource.com/boringssl/)
+- Cloudflare's [fork of QUIC-go](https://github.com/cloudflare/qtls-pq)
+- Goutam Tamvada's [fork of Firefox](https://github.com/xvzcf/firefox-pq-demos)
+- [Open Quantum Safe](https://openquantumsafe.org/) C library
+- [Zig 0.11.0+](https://ziglang.org/)
+- [nginx](https://www.nginx.org/) when [compiled with BoringSSL](https://mailman.nginx.org/pipermail/nginx/2023-August/NOISOYU3QTB2DGIYUBGF7CAMQHDI2QLT.html) ([guide](https://blog.centminmod.com/2023/10/03/2860/how-to-enable-cloudflare-post-quantum-x25519kyber768-key-exchange-support-in-centmin-mod-nginx/))
+- [Caddy HTTP server](https://caddyserver.com/) nightly [compiled with Go 1.23+](https://gist.github.com/bwesterb/2f7bfa7ae689de0d242b56ea3ecac424)
+- [Botan C++ library 3.2.0+](https://botan.randombit.net/) ([instructions](https://github.com/randombit/botan/discussions/3747))
+- ISRG's fork of [Rustls](https://www.memorysafety.org/blog/pq-key-exchange/)

src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx

@@ -0,0 +1,65 @@
+---
+pcx_content_type: how-to
+title: Post-quantum between Cloudflare and origin servers
+sidebar:
+  order: 3
+  label: PQC to your origin
+head: []
+description: Learn about post-quantum cryptography in connections from Cloudflare to your origin servers.
+---
+
+import { Example } from "~/components";
+
+As explained in [About PQC](/ssl/post-quantum-cryptography/), Cloudflare has deployed support for hybrid key agreements, which includes both the most common key agreement for TLS 1.3, X25519, and the post-quantum secure ML-KEM.
+
+With X25519, the [ClientHello](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake/) almost always fits within one network packet. However, with the addition of ML-KEM, the ClientHello is typically split across two packets.
+
+This poses a question of how the origin servers - as well as other middleboxes (routers, load balancers, etc) - will handle this change in behavior. Although allowed by the TLS 1.3 standard ([RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)), a split ClientHello risks not being handled well due to [protocol ossification](https://en.wikipedia.org/wiki/Protocol_ossification) and implementation bugs. Refer to our [blog post](https://blog.cloudflare.com/post-quantum-to-origins/) for details.
+
+## ClientHello from Cloudflare
+
+To reduce the risk of any issues when connecting to servers that are not ready for hybrid key agreements, Cloudflare leverages HelloRetryRequest. This means that, instead of sending [X25519MLKEM768](/ssl/post-quantum-cryptography/#hybrid-key-agreement) immediately as a keyshare [^1], Cloudflare will by default only advertise support for it.
+
+If the origin supports post-quantum hybrid key agreement, it can use HelloRetryRequest to request it from Cloudflare.
+
+## Set up
+
+### Cloudflare zone settings
+
+The method described above is the one Cloudflare uses to support post-quantum to all outbound connections. However, if your origin server supports PQC and prefers it, you can use the [API](/api/operations/zone-cache-settings-change-origin-post-quantum-encryption-setting) to adjust your Cloudflare zone settings and avoid the extra round trip.
+
+It is also possible to opt out of PQC using the same API endpoint.
+
+:::note
+This setting affects all outbound connections from the zone you specify in the API call, including `fetch()` requests made by [Workers](/workers/) on your zone.
+:::
+
+```bash
+curl --request PUT \
+"https://api.cloudflare.com/client/v4/zones/{zone_id}/cache/origin_post_quantum_encryption" \
+--header "Authorization: Bearer <API_TOKEN>" \
+--header "Content-Type: application/json" \
+--data '{
+  "value": "<YOUR_CHOSEN_SETTING>"
+}'
+```
+
+The possible values are:
+- `supported` (most compatible): Advertise support for post-quantum key agreement, but send a classical keyshare in the first ClientHello.
+- `preferred` (most performant): Send a post-quantum keyshare in the first ClientHello. Cloudflare continues to advertise support for classical keyshares as well.
+- `off`: Do not send nor advertise support for post-quantum key agreement to the origin.
+
+### Origin server
+
+To make sure that your origin server prefers the post-quantum key agreement, use the `bssl` tool of [BoringSSL](https://github.com/google/boringssl):
+
+<Example>
+```bash
+$ bssl client -connect (your server):443 -curves X25519MLKEM768
+```
+
+Verify that the `ECDHE curve` in the handshake output indicates `X25519MLKEM768`.
+
+</Example>
+
+[^1]: When, to remove a round trip, a client makes a guess of what the server supports.