From e657aefb4b19e7e4e0041f5f019f2220871f19a4 Mon Sep 17 00:00:00 2001 From: Scott Hart Date: Wed, 7 Oct 2026 15:17:29 -0400 Subject: [PATCH 1/2] doc(auth): add PQC product neutral guide --- .../post-quantum-cryptography.md | 84 +++++++++++++++++++ docfx/product-neutral-guides/CMakeLists.txt | 6 +- 2 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 doc/product-neutral-guides/post-quantum-cryptography.md diff --git a/doc/product-neutral-guides/post-quantum-cryptography.md b/doc/product-neutral-guides/post-quantum-cryptography.md new file mode 100644 index 0000000000000..5ba95484a76aa --- /dev/null +++ b/doc/product-neutral-guides/post-quantum-cryptography.md @@ -0,0 +1,84 @@ +# Google Cloud Platform C++ Client Libraries: Post-Quantum Cryptography (PQC) + +The Google Cloud C++ Client Libraries support Post-Quantum Cryptography (PQC) +for TLS 1.3 connections to protect network traffic against "harvest now, decrypt +later" attacks. + +By default, both gRPC and REST transports negotiate the hybrid post-quantum key +exchange mechanism **`X25519MLKEM768`** (combining classical `X25519` ECDH with +NIST-standardized `ML-KEM-768`) whenever supported by the underlying TLS and +cryptographic libraries. + +## 1. Default Behavior by Transport + +No code changes are required to use PQC when building with supported dependency +versions: + +| Transport | Default Behavior | Minimum Dependency Requirements | +| --------- | ----------------------------------------------------------- | ------------------------------------------------------ | +| **gRPC** | Enabled automatically by gRPC and its TLS stack. | gRPC built with BoringSSL or OpenSSL >= 3.5.0 | +| **REST** | `X25519MLKEM768` is prioritized in `CURLOPT_SSL_EC_CURVES`. | `libcurl >= 7.73.0` with BoringSSL or OpenSSL >= 3.5.0 | + +### REST Transport Details + +When creating a REST connection, the library inspects the linked `libcurl` and +SSL/TLS libraries at runtime. If `X25519MLKEM768` is available, it is prepended +to the list of supported TLS groups passed to `libcurl`. + +If the runtime environment does not support `X25519MLKEM768` (for example, when +linked against OpenSSL < 3.5.0 or `libcurl < 7.73.0`), the client logs an +informational (`INFO`) message and falls back to the default classical curves. + +## 2. Disabling Post-Quantum Cryptography + +In certain network environments, legacy firewalls, proxies, or middleboxes may +drop or time out TLS handshakes containing larger hybrid post-quantum +`ClientHello` key shares. If you encounter TLS handshake failures, you can opt +out of PQC. + +### Disabling PQC with REST + +Set the `GOOGLE_CLOUD_CPP_DISABLE_PQC` environment variable to any value before +starting your application: + +``` +export GOOGLE_CLOUD_CPP_DISABLE_PQC="true" +./my_application +``` + +When `GOOGLE_CLOUD_CPP_DISABLE_PQC` is set, the REST client does not prioritize +`X25519MLKEM768` and leaves the underlying SSL library's default curve order +unchanged. + +### Disabling PQC with gRPC + +The `GOOGLE_CLOUD_CPP_DISABLE_PQC` environment variable only applies to REST +clients. Neither `google-cloud-cpp` nor upstream C++ gRPC provides an +environment variable to disable `X25519MLKEM768` on default credentials. + +To restrict a gRPC client to classical TLS key exchange groups, configure custom +TLS channel credentials using `grpc::experimental::TlsChannelCredentialsOptions` +and pass them via `google::cloud::GrpcCredentialOption`: + +```c +#include "google/cloud/common_options.h" +#include "google/cloud/grpc_options.h" +#include +#include + +google::cloud::Options ConfigureClassicalTlsForGrpc( + std::shared_ptr call_credentials) { + grpc::experimental::TlsChannelCredentialsOptions tls_options; + tls_options.set_key_exchange_groups({ + GRPC_TLS_KEY_EXCHANGE_GROUP_X25519, + GRPC_TLS_KEY_EXCHANGE_GROUP_SECP256R1, + }); + + auto channel_credentials = grpc::CompositeChannelCredentials( + grpc::experimental::TlsCredentials(tls_options), + std::move(call_credentials)); + + return google::cloud::Options{} + .set(std::move(channel_credentials)); +} +``` diff --git a/docfx/product-neutral-guides/CMakeLists.txt b/docfx/product-neutral-guides/CMakeLists.txt index 5b0d62f66cff7..b7302cf3b00aa 100644 --- a/docfx/product-neutral-guides/CMakeLists.txt +++ b/docfx/product-neutral-guides/CMakeLists.txt @@ -8,16 +8,18 @@ add_executable(transform_guides transform_guides.cc) # Define the guide files in separate lists to avoid string(SPLIT). set(guide_target_names "getting-started" "core-concepts" "client-configuration" - "occ" "troubleshooting") + "occ" "post-quantum-cryptography" "troubleshooting") set(guide_source_files "${PROJECT_SOURCE_DIR}/README.md" "${PROJECT_SOURCE_DIR}/doc/product-neutral-guides/core-concepts.md" "${PROJECT_SOURCE_DIR}/doc/product-neutral-guides/client-configuration.md" "${PROJECT_SOURCE_DIR}/doc/product-neutral-guides/occ.md" + "${PROJECT_SOURCE_DIR}/doc/product-neutral-guides/post-quantum-cryptography.md" "${PROJECT_SOURCE_DIR}/doc/product-neutral-guides/troubleshooting.md") set(guide_display_names "Getting Started" "Core Concepts" "Client Configuration" - "Optimistic Concurrency Control (OCC)" "Troubleshooting") + "Optimistic Concurrency Control (OCC)" "Post-Quantum Cryptography (PQC)" + "Troubleshooting") set(copied_files "") set(toc_items "") From f1243ee7aa349a85b37baad5b44649e5ac8e0ea6 Mon Sep 17 00:00:00 2001 From: Scott Hart Date: Wed, 7 Oct 2026 15:22:26 -0400 Subject: [PATCH 2/2] address review comments --- doc/product-neutral-guides/post-quantum-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/product-neutral-guides/post-quantum-cryptography.md b/doc/product-neutral-guides/post-quantum-cryptography.md index 5ba95484a76aa..b26ce2711a57b 100644 --- a/doc/product-neutral-guides/post-quantum-cryptography.md +++ b/doc/product-neutral-guides/post-quantum-cryptography.md @@ -60,7 +60,7 @@ To restrict a gRPC client to classical TLS key exchange groups, configure custom TLS channel credentials using `grpc::experimental::TlsChannelCredentialsOptions` and pass them via `google::cloud::GrpcCredentialOption`: -```c +```cpp #include "google/cloud/common_options.h" #include "google/cloud/grpc_options.h" #include