[SSL/TLS] Bring in PQC content to Dev Docs

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

@@ -0,0 +1,78 @@
+---
+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 implementing post-quantum cryptography to protect you against store now, decrypt later.
+---
+
+For years, Cloudflare has been researching and [writing about post-quantum](https://blog.cloudflare.com/tag/post-quantum/).
+
+To protect you against the risk of [store 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).
+
+:::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), the first, most urgent migration has to do with key agreement.
+
+### Hybrid key agreement
+
+With TLS 1.3, [X25519](https://en.wikipedia.org/wiki/Curve25519) - an Elliptic Curve Diffie-Hellman (ECDH) protocol - is the current standard used 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).
+
+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.
+
+## 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 post-quantum cryptography.
+
+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 the different Cloudflare products and systems have been upgraded to use post-quantum cryptography.
+
+### 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 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,61 @@
+---
+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.
+---
+
+As explained in [About PQC](/ssl/post-quantum-cryptography/), Cloudflare has deployed support for hybrid key agreements, which include both the most common key agreement for TLS 1.3, X25519, and the post-quantum secure ML-KEM.
+
+However, while with X25519 the [ClientHello](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake/) almost always fits within one network packet, with ML-KEM the ClientHello has to be split over two network packets.
+
+This poses a question of how the origin servers - as well as other middleboxes (routers, load balancers, etc) - will handle this behavior. Although allowed by the TLS standard, 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 only advertise support for it.
+
+If the origin supports ML-KEM, it can use HelloRetryRequest to request it from Cloudflare.
+
+## Set up
+
+### Cloudflare zone settings
+
+The method described above is the one used to allow Cloudflare 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 it 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
+
+If you set your Cloudflare zone to `supported`, you can make sure that your origin server will prefer the post-quantum key agreement by using Cloudflare's [fork of BoringSSL](https://github.com/cloudflare/boringssl-pq).
+
+If you set your Cloudflare zone to `preferred`, you can use the `bssl` tool of BoringSSL to check that your origin supports the correct [key agreement](/ssl/post-quantum-cryptography/#hybrid-key-agreement).
+
+```txt
+$ bssl client -connect (your server):443 -curves X25519MLKEM768
+```
+
+
+[^1]: When, to remove a round trip, a client makes a guess of what the server supports.