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

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,78 @@
+---
+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 include 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 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
+
+To make sure that your origin server prefers the post-quantum key agreement:
+
+1. Use Cloudflare's [fork of BoringSSL](https://github.com/cloudflare/boringssl-pq).
+2. Use the `bssl` tool of BoringSSL:
+
+- If you set your Cloudflare zone to `supported`, check that your origin prefers the hybrid key agreement, by using the `-disable-second-keyshare` parameter:
+
+<Example>
+```bash
+$ cd boringssl-pq && cmake -B build && make -C build
+$ build/bssl client -connect (your server):443 -curves X25519:X25519MLKEM768 -disable-second-keyshare
+```
+Verify that the `ECDHE curve` in the handshake output indicates `X25519MLKEM768`.
+</Example>
+
+- If you set your Cloudflare zone to `preferred`, check that your origin supports the correct key agreement:
+
+<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.