docs: Add a Http/Json Post-Quantum Cryptography Guide - #13963
Merged
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive Post-Quantum Cryptography (PQC) User Guide for HTTP/JSON Java Client Libraries. The guide details the quantum threat, library support, Conscrypt integration, platform compatibility, and custom configurations. The review feedback correctly identifies that NetHttpTransport.Builder lacks a setSecurityProvider method in the custom configuration example and provides a valid code suggestion to configure an SSLContext with the custom provider instead.
blakeli0
reviewed
Jul 30, 2026
… steps and locally scoped security providers
…k flow, and format JDK 27 as addendum
…and custom provider builder examples
…JDK 27 addendum scope
… callout on user responsibility
- Frame PQC concepts with beginner-friendly explanations and the two-lock hybrid analogy. - Clarify transport scope: focus exclusively on HTTP/JSON transport and note gRPC coverage in a future PR. - Document handshake size overhead (~1-2KB) and negligible runtime API latency impact due to connection pooling. - Detail deployment compatibility matrix covering glibc Linux, Alpine/musl fallback, and hardened noexec /tmp filesystems. - Add prominent warning on silent fallback tradeoff between high availability and strict regulatory compliance. - Provide step-by-step verification instructions using GAX debug logs and JVM -Djavax.net.debug=ssl:handshake output. - Present modular, non-prescriptive configuration choices (default Conscrypt, classical-only X25519, pure JDK JSSE, dependency exclusion, and custom Bouncy Castle provider). - Add future outlook on OpenJDK native ML-KEM support in JDK 27+.
lqiu96
force-pushed
the
pqc-user-guide
branch
from
September 2, 2026 17:50
67661f5 to
4470661
Compare
- Add Wikipedia link to Shor's algorithm. - Remove conversational introductory phrasing in threat section. - Frame hybrid key exchange as an example rather than a standard. - Remove redundant audience phrasing and generalize endpoint references. - Remove gRPC transport scope section to keep guide focused on HTTP/JSON. - Add OpenJDK link to JEP 496. - Align default named groups list with DEFAULT_CONSCRYPT_NAMED_GROUPS in gax-httpjson. - Clarify fallback to configured security provider (defaulting to standard JDK JSSE). - Moderate latency assertions and encourage user benchmarking. - Remove unsubstantiated CPU benchmark assertions. - Neutralize Alpine Linux options and suggest alternative security providers like Bouncy Castle. - Clean up custom configuration options to only include actionable alternative setups.
Member
Author
|
/gemini review |
lqiu96
marked this pull request as ready for review
September 2, 2026 18:34
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive Post-Quantum Cryptography (PQC) user guide for HTTP/JSON Java client libraries. The feedback points out that the code examples in the custom configuration section use non-existent methods on NetHttpTransport.Builder (specifically setSslSocketConfigurator and setSecurityProvider). To resolve this, the examples should be updated to configure a custom SSLSocketFactory or SSLContext and apply it via setSslSocketFactory.
blakeli0
reviewed
Sep 2, 2026
…ps, and fallback section
…arning example, and rename to Fallback Implications
blakeli0
reviewed
Sep 3, 2026
| The cryptographic landscape is continually advancing. The OpenJDK community is integrating standardized post-quantum algorithms directly into the Java platform: | ||
| - **[JEP 496](https://openjdk.org/jeps/496) (ML-KEM)**: Introduces native implementations of NIST FIPS 203 (Module-Lattice-Based Key-Encapsulation Mechanism) into OpenJDK's standard security providers (`SunJSSE` and `SunJCE`), targeted for **JDK 27+**. | ||
| - **What this means for Google Cloud Java**: Once JDK 27 becomes standard in production environments, Java applications will be capable of negotiating hybrid and pure post-quantum TLS natively without requiring JNI shared libraries or third-party dependencies like Conscrypt. | ||
| - **Future-Proofing**: As native JDK capabilities mature, Google Cloud Java client libraries will adapt to take advantage of built-in JVM providers, preserving a seamless, zero-maintenance security upgrade path for all users. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **Future-Proofing**: As native JDK capabilities mature, Google Cloud Java client libraries will adapt to take advantage of built-in JVM providers, preserving a seamless, zero-maintenance security upgrade path for all users. |
I don't think we want to commit to this.
…e-proofing commitment
blakeli0
approved these changes
Sep 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part 1 of a stack to add pqc guide. This guide is first about Http/Json and a follow up will be with gRPC.