docs: Add gRPC Post-Quantum Cryptography Guide - #14245
Conversation
… 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+.
- 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.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request expands the Post-Quantum Cryptography (PQC) User Guide to cover both gRPC and HTTP/JSON transports, adding comprehensive sections on gRPC transport architecture, platform compatibility, verification methods, and custom configurations. The review feedback suggests correcting the Netty SSL logging instructions to configure the logging framework directly rather than using a JVM system property, and removing an unused import in the gRPC configuration code snippet.
| #### Method 1: Netty SSL Debug Logging | ||
| You can enable debug logging for Netty's shaded SSL handler to observe TLS handshake details: | ||
|
|
||
| ```bash | ||
| java -Dio.grpc.netty.shaded.io.netty.handler.ssl=DEBUG -jar my-application.jar | ||
| ``` |
There was a problem hiding this comment.
Netty's logging is routed through its InternalLoggerFactory, which delegates to the application's active logging framework (such as SLF4J/Logback, Log4j2, or java.util.logging). Passing -Dio.grpc.netty.shaded.io.netty.handler.ssl=TRACE as a JVM system property will not configure the log level. Instead, the log level for the shaded package io.grpc.netty.shaded.io.netty.handler.ssl must be set to TRACE (or FINEST for JUL) within the application's logging configuration file to ensure TLS handshake details are visible.
For example, in a logging.properties file (JUL):
io.grpc.netty.shaded.io.netty.handler.ssl.level=FINESTOr in a Logback configuration (logback.xml):
<logger name="io.grpc.netty.shaded.io.netty.handler.ssl" level="TRACE"/>| #### Method 1: Netty SSL Debug Logging | |
| You can enable debug logging for Netty's shaded SSL handler to observe TLS handshake details: | |
| ```bash | |
| java -Dio.grpc.netty.shaded.io.netty.handler.ssl=DEBUG -jar my-application.jar | |
| ``` | |
| #### Method 1: Netty SSL Trace Logging | |
| You can enable trace logging for Netty's shaded SSL handler to observe TLS handshake details by configuring your logging framework (such as JUL, Logback, or Log4j2) to set the log level for the package "io.grpc.netty.shaded.io.netty.handler.ssl" to TRACE (or FINEST). |
References
- When providing logging examples, use the logging level that will actually show the desired logs, even if it's a more verbose level like FINEST, rather than a less verbose level like FINE, if the actual logs are at the more verbose level.
| import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings; | ||
| import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts; | ||
| import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder; | ||
| import java.io.File; |
There was a problem hiding this comment.
The import java.io.File is not used in this code snippet and can be safely removed to keep the example clean.
…dling and JDK bypass
…, and refine gRPC fallback
…llback to HTTP/JSON, and drop connection characteristics
…ps, and fallback section
…ps, and fallback section
…arning example, and rename to Fallback Implications
…arning example, and rename to Fallback Implications
…e-proofing commitment
…e-proofing commitment
1 participant
Summary
This pull request expands the Post-Quantum Cryptography (PQC) User Guide in
docs/post_quantum_cryptography_guide.mdto cover gRPC transport in addition to HTTP/JSON.This PR is stacked on top of PR #13963 (
pqc-user-guide).Highlights
grpc-netty-shadedtransport engine bundling BoringSSL (netty-tcnative-boringssl-static) with built-in PQC hybrid key exchange support (X25519MLKEM768) in gRPC-Java 1.83.0+.ManagedChannel) and how TLS overhead occurs once upon connection establishment.-Djavax.net.debugflags do not capture gRPC handshakes when usinggrpc-netty-shaded.-Dio.grpc.netty.shaded.io.netty.handler.ssl=DEBUG) andClientInterceptorresponse header verification.InstantiatingGrpcChannelProvider.Builder.setChannelConfigurator(...).