feat(gax-httpjson): Add Post Quantum Cryptography (PQC) Support by default via Conscrypt by lqiu96 · Pull Request #13853 · googleapis/google-cloud-java

lqiu96 · 2026-07-21T19:58:13Z

No description provided.

gemini-code-assist

Code Review

This pull request introduces Post-Quantum Cryptography (PQC) TLS negotiation for HTTP/JSON clients by integrating Conscrypt as a security provider and adding corresponding integration tests. The reviewer feedback focuses on improving the robustness and architecture of this implementation. Specifically, the reviewer recommends removing the undesirable coupling from the core HTTP module to the transport-specific module by defining the PQC groups locally. Additionally, the reviewer suggests wrapping the Conscrypt named groups configuration in a defensive try-catch block and separating the builder creation from the build calls to prevent genuine configuration or mTLS errors from being incorrectly swallowed as Conscrypt loading failures.

gemini-code-assist · 2026-07-21T20:00:31Z

+      try {
+        return new NetHttpTransport.Builder()
+            .setSecurityProvider(Conscrypt.newProvider())
+            .setSslSocketConfigurator(
+                socket -> {
+                  if (Conscrypt.isConscrypt(socket)) {
+                    Conscrypt.setNamedGroups(
+                        socket, InstantiatingHttpJsonChannelProvider.DEFAULT_PQC_GROUPS);
+                  }
+                })
+            .build();
+      } catch (Throwable t) {
+        LOG.log(
+            Level.FINE, "Conscrypt native libraries not available. Falling back to JDK TLS.", t);
+        return new NetHttpTransport.Builder().build();
+      }


Refactor the transport builder initialization to:

Use the locally defined PQC_GROUPS instead of referencing InstantiatingHttpJsonChannelProvider.DEFAULT_PQC_GROUPS.

Wrap the Conscrypt.setNamedGroups call in a defensive try-catch block to prevent runtime connection failures if an older or incompatible version of Conscrypt is present on the classpath.

Separate the builder creation from the build() call so that any potential configuration/build exceptions are not incorrectly swallowed and logged as Conscrypt native library loading failures.

NetHttpTransport.Builder builder = new NetHttpTransport.Builder(); try { builder.setSecurityProvider(Conscrypt.newProvider()) .setSslSocketConfigurator( socket -> { if (Conscrypt.isConscrypt(socket)) { try { Conscrypt.setNamedGroups(socket, PQC_GROUPS); } catch (Exception e) { LOG.log(Level.WARNING, "Failed to set PQC named groups on Conscrypt socket", e); } } }); } catch (Throwable t) { LOG.log( Level.FINE, "Conscrypt native libraries not available. Falling back to JDK TLS.", t); } return builder.build();

References

Avoid inverting layering by making lower-level channel implementations depend on higher-level RPC wrappers. If code is duplicated and needs to be shared, move it to a separate helper/utility class.

gemini-code-assist · 2026-07-21T20:00:31Z

+    try {
+      NetHttpTransport.Builder builder =
+          new NetHttpTransport.Builder()
+              .setSecurityProvider(Conscrypt.newProvider())
+              .setSslSocketConfigurator(
+                  socket -> {
+                    if (Conscrypt.isConscrypt(socket)) {
+                      Conscrypt.setNamedGroups(socket, DEFAULT_PQC_GROUPS);
+                    }
+                  });
+      return configureMtls(builder).build();
+    } catch (Throwable t) {
+      LOG.log(Level.FINE, "Conscrypt native libraries not available. Falling back to JDK TLS.", t);
+      return configureMtls(new NetHttpTransport.Builder()).build();
    }


Refactor the transport builder initialization to:

Wrap the Conscrypt.setNamedGroups call in a defensive try-catch block to prevent runtime connection failures if an older or incompatible version of Conscrypt is present on the classpath.

Separate the builder creation from the configureMtls(builder).build() call. This ensures that any genuine mTLS configuration errors (e.g., key store issues) are correctly propagated to the caller instead of being caught, logged as Conscrypt native library loading failures, and retried.

NetHttpTransport.Builder builder = new NetHttpTransport.Builder(); try { builder.setSecurityProvider(Conscrypt.newProvider()) .setSslSocketConfigurator( socket -> { if (Conscrypt.isConscrypt(socket)) { try { Conscrypt.setNamedGroups(socket, DEFAULT_PQC_GROUPS); } catch (Exception e) { LOG.log(Level.WARNING, "Failed to set PQC named groups on Conscrypt socket", e); } } }); } catch (Throwable t) { LOG.log(Level.FINE, "Conscrypt native libraries not available. Falling back to JDK TLS.", t); } return configureMtls(builder).build();

gemini-code-assist · 2026-07-21T20:00:31Z

 import com.google.api.gax.core.GaxProperties;
 import com.google.api.gax.httpjson.HttpHeadersUtils;
 import com.google.api.gax.httpjson.HttpJsonStatusCode;
+import com.google.api.gax.httpjson.InstantiatingHttpJsonChannelProvider;


This import is unnecessary and introduces an undesirable coupling from the core HTTP module (google-cloud-core-http) to the transport-specific module (gax-httpjson). We can remove this import by defining the PQC groups array locally within this class.

References

Avoid inverting layering by making lower-level channel implementations depend on higher-level RPC wrappers. If code is duplicated and needs to be shared, move it to a separate helper/utility class.

gemini-code-assist · 2026-07-21T20:00:31Z


  public static class DefaultHttpTransportFactory implements HttpTransportFactory {

+    private static final Logger LOG = Logger.getLogger(DefaultHttpTransportFactory.class.getName());


Define the PQC groups array locally to avoid coupling with gax-httpjson.

Suggested change

private static final Logger LOG = Logger.getLogger(DefaultHttpTransportFactory.class.getName());

private static final Logger LOG = Logger.getLogger(DefaultHttpTransportFactory.class.getName());

private static final String[] PQC_GROUPS =

new String[] {"X25519MLKEM768", "SecP256r1MLKEM768", "X25519"};

References

Avoid inverting layering by making lower-level channel implementations depend on higher-level RPC wrappers. If code is duplicated and needs to be shared, move it to a separate helper/utility class.

Is java-core already dependent on gax-httpjson?

This comment was from an older change didn't seem to want to import InstantiatingHttpJsonChannelProvider for constants. Moved it all to a Util class (HttpJsonTransportUtils) that can be shared between the two instead.

lqiu96 · 2026-07-21T20:47:56Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces Post-Quantum Cryptography (PQC) TLS negotiation support for HTTP/JSON clients by registering Conscrypt as the security provider and configuring default PQC named groups. The feedback suggests utilizing lazy initialization and caching for the Conscrypt security provider in both InstantiatingHttpJsonChannelProvider and HttpTransportOptions to prevent the performance and memory overhead of instantiating a new provider on every transport creation.

gemini-code-assist · 2026-07-21T20:50:20Z

+  public static final String[] DEFAULT_PQC_GROUPS =
+      new String[] {"X25519MLKEM768", "SecP256r1MLKEM768", "X25519"};


Prefer lazy initialization and caching for resource-intensive objects like the Conscrypt security provider. Creating a new Provider instance on every transport creation can lead to significant performance overhead and high memory usage.

We can introduce a static lazy holder class to cache the Conscrypt provider instance safely, ensuring it is only initialized once and does not cause class-loading issues if Conscrypt is not present on the classpath.

public static final String[] DEFAULT_PQC_GROUPS = new String[] {"X25519MLKEM768", "SecP256r1MLKEM768", "X25519"}; private static class ConscryptProviderHolder { private static final java.security.Provider INSTANCE = createProvider(); private static java.security.Provider createProvider() { try { return Conscrypt.newProvider(); } catch (Throwable t) { LOG.log( Level.FINE, "Conscrypt native libraries not available. Falling back to JDK TLS.", t); return null; } } }

References

Prefer lazy initialization over eager initialization for resource-intensive objects (such as CharsetEncoder) if they are not guaranteed to be used in all execution paths, to avoid unnecessary performance and memory overhead.

gemini-code-assist · 2026-07-21T20:50:20Z

+    NetHttpTransport.Builder builder = new NetHttpTransport.Builder();
+    try {
+      builder
+          .setSecurityProvider(Conscrypt.newProvider())
+          .setSslSocketConfigurator(
+              socket -> {
+                if (Conscrypt.isConscrypt(socket)) {
+                  try {
+                    Conscrypt.setNamedGroups(socket, DEFAULT_PQC_GROUPS);
+                  } catch (Throwable t) {
+                    // Catch runtime socket configuration errors (e.g. version mismatch or JNI
+                    // error)
+                    // and fall back to Conscrypt's default TLS groups without failing the request.
+                    LOG.log(
+                        Level.FINE,
+                        "Failed to set PQC named groups on Conscrypt socket. Falling back to"
+                            + " Conscrypt default TLS groups.",
+                        t);
+                  }
+                }
+              });
+    } catch (Throwable t) {
+      LOG.log(Level.FINE, "Conscrypt native libraries not available. Falling back to JDK TLS.", t);
+      builder = new NetHttpTransport.Builder();
    }


Use the cached Conscrypt provider instance from ConscryptProviderHolder instead of creating a new provider instance on every call to createHttpTransport(). This avoids unnecessary performance and memory overhead.

NetHttpTransport.Builder builder = new NetHttpTransport.Builder(); java.security.Provider conscryptProvider = ConscryptProviderHolder.INSTANCE; if (conscryptProvider != null) { builder .setSecurityProvider(conscryptProvider) .setSslSocketConfigurator( socket -> { if (Conscrypt.isConscrypt(socket)) { try { Conscrypt.setNamedGroups(socket, DEFAULT_PQC_GROUPS); } catch (Throwable t) { // Catch runtime socket configuration errors (e.g. version mismatch or JNI // error) // and fall back to Conscrypt's default TLS groups without failing the request. LOG.log( Level.FINE, "Failed to set PQC named groups on Conscrypt socket. Falling back to" + " Conscrypt default TLS groups.", t); } } }); }

References

Prefer lazy initialization over eager initialization for resource-intensive objects (such as CharsetEncoder) if they are not guaranteed to be used in all execution paths, to avoid unnecessary performance and memory overhead.

gemini-code-assist · 2026-07-21T20:50:20Z

+    private static final String[] PQC_GROUPS =
+        new String[] {"X25519MLKEM768", "SecP256r1MLKEM768", "X25519"};
    private static final HttpTransportFactory INSTANCE = new DefaultHttpTransportFactory();


Prefer lazy initialization and caching for resource-intensive objects like the Conscrypt security provider. Creating a new Provider instance on every transport creation can lead to significant performance overhead and high memory usage.

We can introduce a static lazy holder class to cache the Conscrypt provider instance safely, ensuring it is only initialized once and does not cause class-loading issues if Conscrypt is not present on the classpath.

private static final String[] PQC_GROUPS = new String[] {"X25519MLKEM768", "SecP256r1MLKEM768", "X25519"}; private static final HttpTransportFactory INSTANCE = new DefaultHttpTransportFactory(); private static class ConscryptProviderHolder { private static final java.security.Provider INSTANCE = createProvider(); private static java.security.Provider createProvider() { try { return Conscrypt.newProvider(); } catch (Throwable t) { LOG.log( Level.FINE, "Conscrypt native libraries not available. Falling back to JDK TLS.", t); return null; } } }

References

Prefer lazy initialization over eager initialization for resource-intensive objects (such as CharsetEncoder) if they are not guaranteed to be used in all execution paths, to avoid unnecessary performance and memory overhead.

gemini-code-assist · 2026-07-21T20:50:20Z

+      NetHttpTransport.Builder builder = new NetHttpTransport.Builder();
+      try {
+        builder
+            .setSecurityProvider(Conscrypt.newProvider())
+            .setSslSocketConfigurator(
+                socket -> {
+                  if (Conscrypt.isConscrypt(socket)) {
+                    try {
+                      Conscrypt.setNamedGroups(socket, PQC_GROUPS);
+                    } catch (Throwable t) {
+                      // Catch runtime socket configuration errors (e.g. version mismatch or JNI
+                      // error)
+                      // and fall back to Conscrypt's default TLS groups without failing the
+                      // request.
+                      LOG.log(
+                          Level.FINE,
+                          "Failed to set PQC named groups on Conscrypt socket. Falling back to"
+                              + " Conscrypt default TLS groups.",
+                          t);
+                    }
+                  }
+                });
+      } catch (Throwable t) {
+        LOG.log(
+            Level.FINE, "Conscrypt native libraries not available. Falling back to JDK TLS.", t);
+        builder = new NetHttpTransport.Builder();
+      }


Use the cached Conscrypt provider instance from ConscryptProviderHolder instead of creating a new provider instance on every call to create(). This avoids unnecessary performance and memory overhead.

NetHttpTransport.Builder builder = new NetHttpTransport.Builder(); java.security.Provider conscryptProvider = ConscryptProviderHolder.INSTANCE; if (conscryptProvider != null) { builder .setSecurityProvider(conscryptProvider) .setSslSocketConfigurator( socket -> { if (Conscrypt.isConscrypt(socket)) { try { Conscrypt.setNamedGroups(socket, PQC_GROUPS); } catch (Throwable t) { // Catch runtime socket configuration errors (e.g. version mismatch or JNI // error) // and fall back to Conscrypt's default TLS groups without failing the // request. LOG.log( Level.FINE, "Failed to set PQC named groups on Conscrypt socket. Falling back to" + " Conscrypt default TLS groups.", t); } } }); }

References

Prefer lazy initialization over eager initialization for resource-intensive objects (such as CharsetEncoder) if they are not guaranteed to be used in all execution paths, to avoid unnecessary performance and memory overhead.

blakeli0 · 2026-07-22T03:17:13Z

+              }
+              try {
+                Conscrypt.setNamedGroups(socket, DEFAULT_PQC_GROUPS);
+              } catch (Throwable t) {


Are there known checked exceptions? If not, catching Exception is fine but catching Throwable might hide larger problems. e.g. Even if a version mismatch is ignored here, it might blow up in other places.

blakeli0 · 2026-07-22T03:19:01Z

+   *
+   * <p>Returns {@code null} on failure so that transport creation can fall back to default JDK TLS,
+   * ensuring that setting Conscrypt as the default security provider does not cause breaking
+   * failures for customers running on environments where Conscrypt is unsupported or unavailable.


where Conscrypt is unsupported

What error would we run into?

blakeli0 · 2026-07-22T03:20:26Z


  public static class DefaultHttpTransportFactory implements HttpTransportFactory {

+    private static final Logger LOG = Logger.getLogger(DefaultHttpTransportFactory.class.getName());


Is java-core already dependent on gax-httpjson?

blakeli0 · 2026-07-22T03:20:40Z

+   *       standard TLS 1.3 endpoints if ML-KEM is not negotiated.
+   * </ul>
+   */
+  public static final String[] DEFAULT_PQC_GROUPS =


Does this need to be public?

removed visibility (public was a remnant from an older change)

…qc-verification sample module

…streamline Conscrypt try-fallback

…rator in try block and remove draft Javadoc

…h blocks in GAX and Core HTTP

…pt is unavailable

…annelProviderTest

…n GAX and Core HTTP

…lProviderTest and HttpTransportOptionsTest

…t exception and restore HttpTransportOptionsTest to main

…ryptPqcConfiguratorHelper

…t classical non-PQC test case

… helper Javadocs

…ation in ITPqc

… handling

…socket configurator

…nstance

…Conscrypt log level to WARNING

…scrypt PQC fallback

…ransportUtils

…crypt Javadoc

…rHolder and comment catch block

…tProviderHolder Javadoc

…ptography

…tcp readiness polling loop

…snapshot repositories

…on for Java 8 compatibility

…n pqc-httpjson-support

…uantumCryptography without constructing custom transport

… configureConscryptSecurityProvider

sonarqubecloud · 2026-07-22T18:02:12Z

Quality Gate failed for 'gapic-generator-java-root'

Failed conditions
57.9% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

sonarqubecloud · 2026-07-22T18:03:48Z

Quality Gate failed for 'gapic-generator-java-root'

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

gemini-code-assist Bot reviewed Jul 21, 2026

View reviewed changes

lqiu96 force-pushed the pqc-httpjson-support branch from 218f3e6 to 1a08829 Compare July 21, 2026 21:54

blakeli0 reviewed Jul 22, 2026

View reviewed changes

lqiu96 added 25 commits July 22, 2026 17:30

feat(httpjson): add Conscrypt PQC support for HttpJson transports

708dad6

refactor(httpjson): restrict ITPqc to HttpJson PQC tests and remove p…

e1e6de1

…qc-verification sample module

refactor(httpjson): remove X25519Kyber768Draft00 from PQC groups and …

8bf75d3

…streamline Conscrypt try-fallback

refactor(httpjson): group setSecurityProvider and setSslSocketConfigu…

d371aa4

…rator in try block and remove draft Javadoc

docs(pqc): add detailed explanatory comments above Conscrypt try-catc…

d1ce9cd

…h blocks in GAX and Core HTTP

docs(pqc): add Level.FINE logger to HttpTransportOptions when Conscry…

086faf0

…pt is unavailable

test(httpjson): remove reflection helper from InstantiatingHttpJsonCh…

94d825b

…annelProviderTest

test(pqc): add unit tests for PQC Conscrypt transport configuration i…

5078cb9

…n GAX and Core HTTP

test(pqc): clean up reflection tests from InstantiatingHttpJsonChanne…

8d936f7

…lProviderTest and HttpTransportOptionsTest

refactor(pqc): fallback to fresh NetHttpTransport.Builder on Conscryp…

baf5769

…t exception and restore HttpTransportOptionsTest to main

refactor(showcase): streamline ITPqc transport setup and remove Consc…

afbae79

…ryptPqcConfiguratorHelper

refactor(showcase): remove isConscryptFunctional fallback and restric…

3f0bec3

…t classical non-PQC test case

refactor(showcase): address PR review comments for ITPqc.java and add…

e334f80

… helper Javadocs

docs(showcase): clarify rationale for classical named groups configur…

f17b615

…ation in ITPqc

refactor(http): decouple PQC constants and add defensive lambda error…

273a3f9

… handling

fix(http): update log level to FINE and clarify fallback message for …

46aaed3

…socket configurator

perf(http): lazily initialize and cache Conscrypt security provider i…

bc541e0

…nstance

refactor(http): use early returns in createHttpTransport and upgrade …

ee8b99d

…Conscrypt log level to WARNING

docs(http): document architectural tradeoff decision for graceful Con…

36f7601

…scrypt PQC fallback

refactor(http): centralize Conscrypt PQC transport logic in HttpJsonT…

f30f266

…ransportUtils

docs(http): update Conscrypt PQC Javadoc comments and method naming

a52c88e

refactor(http): remove duplicate DEFAULT_PQC_GROUPS and simplify Cons…

7e5b30d

…crypt Javadoc

docs(http): move environment fallback explanation to ConscryptProvide…

b310138

…rHolder and comment catch block

docs(http): clarify caching rationale vs JDK TLS fallback in Conscryp…

8e31771

…tProviderHolder Javadoc

refactor(showcase): rename ITPqc integration test to ITPostQuantumCry…

3f3fcd4

…ptography

lqiu96 added 6 commits July 22, 2026 17:30

ci(showcase): replace hardcoded sleep 2 with deterministic Bash /dev/…

18cb2c3

…tcp readiness polling loop

deps(grpc): upgrade gRPC-Java to official release v1.83.0 and remove …

5e0e429

…snapshot repositories

fix(showcase): fix Java 8 compilation in ITPostQuantumCryptography

384f672

fix(showcase): use Conscrypt.setNamedGroups directly without reflecti…

5004ec3

…on for Java 8 compatibility

revert(pqc): restore grpc, guava, errorprone versions to match main o…

c28ce89

…n pqc-httpjson-support

test(showcase): test default PQC NetHttpTransport creation in ITPostQ…

50e0e64

…uantumCryptography without constructing custom transport

lqiu96 force-pushed the pqc-httpjson-support branch from b27c1ca to 50e0e64 Compare July 22, 2026 17:31

refactor(gax-httpjson): rename createConscryptHttpTransportBuilder to…

44ce5a3

… configureConscryptSecurityProvider


		public static class DefaultHttpTransportFactory implements HttpTransportFactory {

		private static final Logger LOG = Logger.getLogger(DefaultHttpTransportFactory.class.getName());

		public static final String[] DEFAULT_PQC_GROUPS =
		new String[] {"X25519MLKEM768", "SecP256r1MLKEM768", "X25519"};

Uh oh!

Conversation

lqiu96 commented Jul 21, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

blakeli0 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

lqiu96 Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lqiu96 commented Jul 21, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

blakeli0 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

blakeli0 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

blakeli0 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

blakeli0 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

lqiu96 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud Bot commented Jul 22, 2026

Quality Gate failed for 'gapic-generator-java-root'

Uh oh!

sonarqubecloud Bot commented Jul 22, 2026

Quality Gate failed for 'gapic-generator-java-root'

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lqiu96 Jul 22, 2026 •

edited

Loading