From 97c282571aa99a899107a2a60a213311051f9716 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 14 Nov 2024 11:49:55 +0000 Subject: [PATCH 01/25] Add placeholders for new folder and pages and fill in frontmatter --- .../docs/ssl/post-quantum-cryptography/index.mdx | 12 ++++++++++++ .../ssl/post-quantum-cryptography/pqc-to-origin.mdx | 9 +++++++++ .../docs/ssl/post-quantum-cryptography/reference.mdx | 8 ++++++++ 3 files changed, 29 insertions(+) create mode 100644 src/content/docs/ssl/post-quantum-cryptography/index.mdx create mode 100644 src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx create mode 100644 src/content/docs/ssl/post-quantum-cryptography/reference.mdx diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx new file mode 100644 index 000000000000000..884142613803866 --- /dev/null +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -0,0 +1,12 @@ +--- +pcx_content_type: concept +title: Post-quantum cryptography (PQC) +sidebar: + order: 9 + label: About PQC + group: + label: Post-quantum +head: [] +description: Consider information about how Cloudflare is implementing post-quantum cryptography to protect you against store now, decrypt later. +--- + diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx new file mode 100644 index 000000000000000..f0a2e56c794bd1e --- /dev/null +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -0,0 +1,9 @@ +--- +pcx_content_type: how-to +title: Enable PQC to your origin +sidebar: + order: 2 + label: PQC to your origin +head: [] +description: Learn how to enabled post-quantum cryptography in connections from Cloudflare to your origin servers. +--- \ No newline at end of file diff --git a/src/content/docs/ssl/post-quantum-cryptography/reference.mdx b/src/content/docs/ssl/post-quantum-cryptography/reference.mdx new file mode 100644 index 000000000000000..20763e19fad1e0e --- /dev/null +++ b/src/content/docs/ssl/post-quantum-cryptography/reference.mdx @@ -0,0 +1,8 @@ +--- +pcx_content_type: reference +title: PQC support +sidebar: + order: 3 +head: [] +description: Consider information about post-quantum cryptography at Cloudflare - deployed key agreements, software support, protected products, and more. +--- \ No newline at end of file From 39905538c7e586505ef4a46f6b458372197f4a45 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 14 Nov 2024 16:17:12 +0000 Subject: [PATCH 02/25] Add outline for index.mdx and fill in TLS background info --- .../ssl/post-quantum-cryptography/index.mdx | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 884142613803866..5558f097a7a6f91 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -10,3 +10,32 @@ head: [] description: Consider information about 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. + +:::caution[TLS 1.3] +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 + +For a TLS handshake to happen, three types of encryption have to be in place: + +- **Symmetric ciphers:** used to encrypt and decrypt data, ensuring confidentiality and integrity (such as `CHACHA20-POLY1305`). +- **Key agreement:** a cryptographic protocol with which client and server can 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 that needs to happen has to do with key agreement. + +### Hybrid key agreement + +## Three connections in the life of a request + +### Visitor to Cloudflare + +As of [october 2023](https://blog.cloudflare.com/post-quantum-for-all/), all websites and APIs served through Cloudflare support post-quantum hybrid key agreement. + +### Internal services + +### Cloudflare to your origin \ No newline at end of file From a6bfb7fad45bcd8d51f8ab26c9dae20172b472cc Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Fri, 15 Nov 2024 09:23:42 +0000 Subject: [PATCH 03/25] Apply suggestion: Reword intro to TLS building blocks Co-authored-by: Peter Wu --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 5558f097a7a6f91..def25c099c0d5dc 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -20,7 +20,7 @@ Post-quantum key agreements are only supported in protocols based on TLS 1.3 (in ## Three building blocks of TLS -For a TLS handshake to happen, three types of encryption have to be in place: +Before TLS can protect your communications, three cryptographic algorithms have to be agreed on during the TLS handshake: - **Symmetric ciphers:** used to encrypt and decrypt data, ensuring confidentiality and integrity (such as `CHACHA20-POLY1305`). - **Key agreement:** a cryptographic protocol with which client and server can safely agree on a shared key (such as `ECDH`). From 9a2e327b037787b7963d3e2a09b932d4187cd57a Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 15 Nov 2024 09:30:48 +0000 Subject: [PATCH 04/25] Fix typo and reword index.mdx meta description --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 2 +- .../docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index def25c099c0d5dc..ea4b1fc93dfc337 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -7,7 +7,7 @@ sidebar: group: label: Post-quantum head: [] -description: Consider information about how Cloudflare is implementing post-quantum cryptography to protect you against store now, decrypt later. +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/). diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index f0a2e56c794bd1e..7808c53e6e3cb4b 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -5,5 +5,5 @@ sidebar: order: 2 label: PQC to your origin head: [] -description: Learn how to enabled post-quantum cryptography in connections from Cloudflare to your origin servers. +description: Learn how to enable post-quantum cryptography in connections from Cloudflare to your origin servers. --- \ No newline at end of file From 691a805c79417146831dc8e57f579191dcc8ed1e Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 15 Nov 2024 14:50:22 +0000 Subject: [PATCH 05/25] Improve parallelism, refine text, and link out to TLS handshake LC --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index ea4b1fc93dfc337..ae1d323871ce55f 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -20,10 +20,10 @@ Post-quantum key agreements are only supported in protocols based on TLS 1.3 (in ## Three building blocks of TLS -Before TLS can protect your communications, three cryptographic algorithms have to be agreed on during the TLS handshake: +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:** used to encrypt and decrypt data, ensuring confidentiality and integrity (such as `CHACHA20-POLY1305`). -- **Key agreement:** a cryptographic protocol with which client and server can safely agree on a shared key (such as `ECDH`). +- **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 that needs to happen has to do with key agreement. From 55a8f2a05d06ecacd76cd865f30987f7c84b34bb Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 15 Nov 2024 15:43:11 +0000 Subject: [PATCH 06/25] Fill in hybrid key agreement section --- .../ssl/post-quantum-cryptography/index.mdx | 21 +++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index ae1d323871ce55f..856bdc7acbc78db 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -22,14 +22,27 @@ Post-quantum key agreements are only supported in protocols based on TLS 1.3 (in 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`). +- **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 that needs to happen has to do with key agreement. +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](#visitor-to-cloudflare) adopt post-quantum cryptograph, 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 ### Visitor to Cloudflare From 7740221af7a328a8ac48ad10f7b28287cb89ab4c Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 15 Nov 2024 15:51:00 +0000 Subject: [PATCH 07/25] Complete visitor-to-cloudflare intro paragraph --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 856bdc7acbc78db..63e039d5d37a73c 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -47,7 +47,7 @@ A hybrid key agreement lays the groundwork as more and more [clients](#visitor-t ### Visitor to Cloudflare -As of [october 2023](https://blog.cloudflare.com/post-quantum-for-all/), all websites and APIs served through Cloudflare support post-quantum hybrid key agreement. +As of [october 2023](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. ### Internal services From 7e0b9a15e38c7447179243e8804e6a7b56418d89 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 15 Nov 2024 16:06:28 +0000 Subject: [PATCH 08/25] Add mermaid digram for connections and reword #2 --- .../ssl/post-quantum-cryptography/index.mdx | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 63e039d5d37a73c..5dabb1d572a5df1 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -45,10 +45,26 @@ A hybrid key agreement lays the groundwork as more and more [clients](#visitor-t ## Three connections in the life of a request -### Visitor to Cloudflare +```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
service A)] + B[(Cloudflare
service B)] + end + C[(Origin server)] + + A --1--> X + X --2--> B + B --3--> C +``` + +### 1. Visitor to Cloudflare As of [october 2023](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. -### Internal services +### 2. Internal connections -### Cloudflare to your origin \ No newline at end of file +### 3. Cloudflare to your origin \ No newline at end of file From 8d5d0c8b67574443cb2f8939b4fb82207dce3bf7 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Fri, 15 Nov 2024 16:07:35 +0000 Subject: [PATCH 09/25] Fix Internet capitalization Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 5dabb1d572a5df1..4e790c3fde119ba 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -32,7 +32,7 @@ As explained in our [blog post](https://blog.cloudflare.com/pq-2024/#two-migrati 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/). +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: From f81512262c3c5accf15f7f800b9f358ea8661622 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 18 Nov 2024 14:38:59 +0000 Subject: [PATCH 10/25] Rename file, fill in, and link to pqc-support --- .../ssl/post-quantum-cryptography/index.mdx | 6 ++- .../post-quantum-cryptography/pqc-support.mdx | 38 +++++++++++++++++++ .../post-quantum-cryptography/reference.mdx | 8 ---- 3 files changed, 43 insertions(+), 9 deletions(-) create mode 100644 src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx delete mode 100644 src/content/docs/ssl/post-quantum-cryptography/reference.mdx diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 4e790c3fde119ba..875f3abe5d578b8 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -41,7 +41,7 @@ Cloudflare has deployed the following hybrid key agreements: - [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](#visitor-to-cloudflare) adopt post-quantum cryptograph, 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. +A hybrid key agreement lays the groundwork as more and more [clients](#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 @@ -65,6 +65,10 @@ flowchart LR As of [october 2023](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 + + ### 3. Cloudflare to your origin \ No newline at end of file diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx new file mode 100644 index 000000000000000..3f41242d1c0281d --- /dev/null +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx @@ -0,0 +1,38 @@ +--- +pcx_content_type: reference +title: PQC support +sidebar: + order: 3 +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 the following [third-parties](#software-support) and is in use within the following [Cloudflare products](#cloudflare-products). + +## Software support + +### 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/) \ No newline at end of file diff --git a/src/content/docs/ssl/post-quantum-cryptography/reference.mdx b/src/content/docs/ssl/post-quantum-cryptography/reference.mdx deleted file mode 100644 index 20763e19fad1e0e..000000000000000 --- a/src/content/docs/ssl/post-quantum-cryptography/reference.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -pcx_content_type: reference -title: PQC support -sidebar: - order: 3 -head: [] -description: Consider information about post-quantum cryptography at Cloudflare - deployed key agreements, software support, protected products, and more. ---- \ No newline at end of file From 501a6d5642ff4473e32fc8b1f7be68459c753586 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 18 Nov 2024 15:11:55 +0000 Subject: [PATCH 11/25] Fix capitalization and fill in Intenal connections section --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 875f3abe5d578b8..531e0180fc5e115 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -63,12 +63,13 @@ flowchart LR ### 1. Visitor to Cloudflare -As of [october 2023](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. +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 -### 3. Cloudflare to your origin \ No newline at end of file From 769a0df653d7c6f478af4e0c702799213811047b Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 19 Nov 2024 10:09:01 +0000 Subject: [PATCH 12/25] Fill in Cf to origin and review titles and headings --- .../docs/ssl/post-quantum-cryptography/index.mdx | 11 +++++++---- .../ssl/post-quantum-cryptography/pqc-support.mdx | 10 ++++------ .../ssl/post-quantum-cryptography/pqc-to-origin.mdx | 7 ++++--- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 531e0180fc5e115..2255c828f2d4844 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -10,12 +10,12 @@ 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/). +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. +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] -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). +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 @@ -41,7 +41,7 @@ Cloudflare has deployed the following hybrid key agreements: - [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](#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. +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 @@ -73,3 +73,6 @@ As announced in [September 2023](https://blog.cloudflare.com/post-quantum-crypto ### 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. \ No newline at end of file diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx index 3f41242d1c0281d..6996997425f7ef8 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx @@ -2,22 +2,20 @@ pcx_content_type: reference title: PQC support sidebar: - order: 3 + 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 the following [third-parties](#software-support) and is in use within the following [Cloudflare products](#cloudflare-products). +Cloudflare's deployment of post-quantum hybrid key agreements is supported by different software as listed below. -## Software support - -### X25519MLKEM768 +## 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 +## 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`. diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 7808c53e6e3cb4b..4797cd3688c5027 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -1,9 +1,10 @@ --- pcx_content_type: how-to -title: Enable PQC to your origin +title: Post-quantum between Cloudflare and origin servers sidebar: - order: 2 + order: 3 label: PQC to your origin head: [] description: Learn how to enable post-quantum cryptography in connections from Cloudflare to your origin servers. ---- \ No newline at end of file +--- + From d8a58a805492c995b882ea59ca746d5716ff58ef Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 19 Nov 2024 14:48:41 +0000 Subject: [PATCH 13/25] Fix missing hyphen and touch up pqc-to-origin description --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 2 +- .../docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 2255c828f2d4844..d6884785b47e7aa 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -69,7 +69,7 @@ Refer to [Post-quantum cryptography support](/ssl/post-quantum-cryptography/pqc- ### 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. +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 diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 4797cd3688c5027..0d9f85bdd33e363 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -5,6 +5,6 @@ sidebar: order: 3 label: PQC to your origin head: [] -description: Learn how to enable post-quantum cryptography in connections from Cloudflare to your origin servers. +description: Learn about post-quantum cryptography in connections from Cloudflare to your origin servers. --- From 8b65760ecdf0d1c3dc58f81643f17d59316442fd Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 19 Nov 2024 15:34:39 +0000 Subject: [PATCH 14/25] Add split ClientHello and HRR workaround to pqc-to-origin --- .../ssl/post-quantum-cryptography/pqc-to-origin.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 0d9f85bdd33e363..86940c7c67d79a9 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -8,3 +8,16 @@ 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. + +[^1]: When, to remove a round trip, a client makes a guess of what the server supports. \ No newline at end of file From 05fe350734ff3eb5f98b53a50e9ceaf1863d2896 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 19 Nov 2024 16:33:20 +0000 Subject: [PATCH 15/25] Add setup instructions to pqc-to-origin --- .../pqc-to-origin.mdx | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 86940c7c67d79a9..0ebb22cae2d631c 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -20,4 +20,42 @@ To reduce the risk of any issues when connecting to servers that are not ready f 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 " \ +--header "Content-Type: application/json" \ +--data '{ + "value": "" +}' +``` + +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. \ No newline at end of file From 2fc8ef75033bce0b01e65f7cbc1fe1620850415f Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Tue, 19 Nov 2024 16:41:22 +0000 Subject: [PATCH 16/25] Apply suggestion from code review Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- .../docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 0ebb22cae2d631c..66f2491e68a9a86 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -29,7 +29,7 @@ The method described above is the one used to allow Cloudflare to support post-q 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. +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 From 0e02cc436af4b232d3cd6e848ecabbce1508c1e9 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Wed, 20 Nov 2024 15:17:47 +0000 Subject: [PATCH 17/25] Apply suggestions from code review Co-authored-by: Luke Valenta Co-authored-by: Suleman Ahmad <36677672+SulemanAhmadd@users.noreply.github.com> --- .../docs/ssl/post-quantum-cryptography/index.mdx | 14 +++++++------- .../post-quantum-cryptography/pqc-to-origin.mdx | 8 ++++---- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index d6884785b47e7aa..f078249d3d0bbc7 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -7,12 +7,12 @@ sidebar: 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. +description: Get an overview of how Cloudflare is deploying 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/). +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 [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). +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). :::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). @@ -26,11 +26,11 @@ Before TLS can protect your communications, three cryptographic algorithms have - **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. +As explained in our [blog post](https://blog.cloudflare.com/pq-2024/#two-migrations), it is urgent to migrate key agreement to post-quantum algorithms as soon as possible to protect against an adversary capable of storing today's encrypted communications until some time in the future when they can gain access to a sufficiently powerful quantum computer with which they can decrypt. ### 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). +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). 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/). @@ -63,13 +63,13 @@ flowchart LR ### 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. +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 the different Cloudflare products and systems have been upgraded to use post-quantum cryptography. +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 diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 66f2491e68a9a86..1568a1c6beebf3b 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -10,15 +10,15 @@ description: Learn about post-quantum cryptography in connections from Cloudflar 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. +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 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. +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://datatracker.ietf.org/doc/html/rfc8446)), 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. +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 ML-KEM, it can use HelloRetryRequest to request it from Cloudflare. +If the origin supports post-quantum hybrid key agreement, it can use HelloRetryRequest to request it from Cloudflare. ## Set up From f029142e992c96da0ef8595b392b03b3aa3add51 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 20 Nov 2024 15:41:36 +0000 Subject: [PATCH 18/25] Replace store by harvest, adjust RFC link cf Style Guide, and split long paragarph --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 4 ++-- .../docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index f078249d3d0bbc7..91fbbfa3ffaec0f 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -7,7 +7,7 @@ sidebar: group: label: Post-quantum head: [] -description: Get an overview of how Cloudflare is deploying post-quantum cryptography to protect you against store now, decrypt later. +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. @@ -26,7 +26,7 @@ Before TLS can protect your communications, three cryptographic algorithms have - **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), it is urgent to migrate key agreement to post-quantum algorithms as soon as possible to protect against an adversary capable of storing today's encrypted communications until some time in the future when they can gain access to a sufficiently powerful quantum computer with which they can decrypt. +As explained in our [blog post](https://blog.cloudflare.com/pq-2024/#two-migrations), 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. ### Hybrid key agreement diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 1568a1c6beebf3b..0c2261914401032 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -12,7 +12,7 @@ As explained in [About PQC](/ssl/post-quantum-cryptography/), Cloudflare has dep 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://datatracker.ietf.org/doc/html/rfc8446)), 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. +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 From 66bd9f8623dc7dc40beb88a9b98cce18ff2ea24f Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 20 Nov 2024 16:26:02 +0000 Subject: [PATCH 19/25] Add reference to PQ signatures and link out to blog --- .../docs/ssl/post-quantum-cryptography/index.mdx | 10 +++++++++- .../docs/ssl/post-quantum-cryptography/pqc-support.mdx | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 91fbbfa3ffaec0f..5869256032cf8af 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -26,12 +26,14 @@ Before TLS can protect your communications, three cryptographic algorithms have - **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), 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. +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: @@ -43,6 +45,12 @@ Cloudflare has deployed the following hybrid key agreements: 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 diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx index 6996997425f7ef8..1c89cbb7fe937c6 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx @@ -7,7 +7,7 @@ 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. +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) From e11cab48e226844690863355dbf5a2b14dfa8867 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 21 Nov 2024 11:58:01 +0000 Subject: [PATCH 20/25] Fix origin server section to use fork and bssl for both cases --- .../pqc-to-origin.mdx | 25 ++++++++++++++++--- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 0c2261914401032..66b1ab98f34148c 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -8,6 +8,8 @@ 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. @@ -49,13 +51,28 @@ The possible values are: ### 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). +To make sure that your origin server prefers the post-quantum key agreement: -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). +1. Use Cloudflare's [fork of BoringSSL](https://github.com/cloudflare/boringssl-pq). +2. Use the `bssl` tool of BoringSSL: -```txt -$ bssl client -connect (your server):443 -curves X25519MLKEM768 +- If you set your Cloudflare zone to `supported`, check that your origin prefers the hybrid key agreement, by using the `-disable-second-keyshare` parameter: + + +```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`. + +- If you set your Cloudflare zone to `preferred`, check that your origin supports the correct key agreement: + + +```bash +$ bssl client -connect (your server):443 -curves X25519MLKEM768 +``` +Verify that the `ECDHE curve` in the handshake output indicates `X25519MLKEM768`. + [^1]: When, to remove a round trip, a client makes a guess of what the server supports. \ No newline at end of file From ed2f4c054df4d41795c12a4c3f3a304ad8c41dde Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:59:26 +0000 Subject: [PATCH 21/25] Add link to Cloudflare Radar Co-authored-by: Luke Valenta --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 5869256032cf8af..1dd26469f4a19b9 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -71,7 +71,7 @@ flowchart LR ### 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. +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. See [Cloudflare Radar](https://radar.cloudflare.com/adoption-and-usage#post-quantum-encryption-adoption) for current statistics on PQ encryption adoption in requests to Cloudflare. 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. From ce59ab90900564cf48f20299aec949496ef8d6d2 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 21 Nov 2024 12:07:56 +0000 Subject: [PATCH 22/25] Text review and move link to Radar higher up in the page --- src/content/docs/ssl/post-quantum-cryptography/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/index.mdx b/src/content/docs/ssl/post-quantum-cryptography/index.mdx index 1dd26469f4a19b9..b4441080bdbe712 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/index.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/index.mdx @@ -14,6 +14,8 @@ Post-quantum cryptography (PQC) refers to cryptographic algorithms that have bee 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). ::: @@ -71,7 +73,7 @@ flowchart LR ### 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. See [Cloudflare Radar](https://radar.cloudflare.com/adoption-and-usage#post-quantum-encryption-adoption) for current statistics on PQ encryption adoption in requests 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. From cf3fd60b7cc674ef826aafdee8e9393c6d77f594 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Fri, 22 Nov 2024 10:02:27 +0000 Subject: [PATCH 23/25] Simplify origin server instructions to use BoringSSL instead of fork Co-authored-by: Suleman Ahmad <36677672+SulemanAhmadd@users.noreply.github.com> --- .../docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 66b1ab98f34148c..57e6a945fc5f8ee 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -51,7 +51,13 @@ The possible values are: ### Origin server -To make sure that your origin server prefers the post-quantum key agreement: +To make sure that your origin server prefers the post-quantum key agreement use the `bssl` tool of [BoringSSL](https://github.com/google/boringssl): + + +```bash +$ bssl client -connect (your server):443 -curves X25519MLKEM768 ``` +Verify that the `ECDHE curve` in the handshake output indicates `X25519MLKEM768`. + 1. Use Cloudflare's [fork of BoringSSL](https://github.com/cloudflare/boringssl-pq). 2. Use the `bssl` tool of BoringSSL: From 7f6dfeabed04a945a00df6edd58bcdee3be95e64 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 22 Nov 2024 10:19:28 +0000 Subject: [PATCH 24/25] Overall text review and remove previous origin instructions --- .../pqc-to-origin.mdx | 27 +++---------------- 1 file changed, 4 insertions(+), 23 deletions(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 57e6a945fc5f8ee..88c65b1ad10abe6 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -26,7 +26,7 @@ If the origin supports post-quantum hybrid key agreement, it can use HelloRetryR ### 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. +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. @@ -51,34 +51,15 @@ The possible values are: ### 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): - - -```bash -$ bssl client -connect (your server):443 -curves X25519MLKEM768 ``` -Verify that the `ECDHE curve` in the handshake output indicates `X25519MLKEM768`. - - -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: - - -```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`. - - -- If you set your Cloudflare zone to `preferred`, check that your origin supports the correct key agreement: +To make sure that your origin server prefers the post-quantum key agreement, use the `bssl` tool of [BoringSSL](https://github.com/google/boringssl): ```bash $ bssl client -connect (your server):443 -curves X25519MLKEM768 ``` + Verify that the `ECDHE curve` in the handshake output indicates `X25519MLKEM768`. + [^1]: When, to remove a round trip, a client makes a guess of what the server supports. \ No newline at end of file From 49f5b90c55fa2d792ca41fcd6f31e2a32049be94 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Fri, 22 Nov 2024 15:26:07 +0000 Subject: [PATCH 25/25] Apply suggestion from code review Co-authored-by: Jun Lee --- .../docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx index 88c65b1ad10abe6..9898736e3e1ccae 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-to-origin.mdx @@ -10,7 +10,7 @@ description: Learn about post-quantum cryptography in connections from Cloudflar 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. +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.