Skip to content

Commit 360cf6f

Browse files
lqiu96lqiu96
committed
feat: add pqc-verification module with BigQuery sample and setup README
TAG=agy CONV=385b9ab5-874c-4c9a-b331-66dab51fef61
1 parent 945a336 commit 360cf6f

3 files changed

Lines changed: 457 additions & 0 deletions

File tree

‎pqc-verification/README.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# GAPIC Post-Quantum Cryptography (PQC) Support & Verification
2+
3+
This directory contains verification tools and samples to test, trace, and verify Post-Quantum Cryptography (PQC) support in Google Cloud Java client libraries, covering both gRPC and HttpJson (REST) transports.
4+
5+
---
6+
7+
## 1. Prerequisites & Dependencies
8+
9+
### Java Version
10+
* To perform PQC handshakes, JDK 11+ is required for compiling Conscrypt. JDK 17+ or JDK 21+ is highly recommended.
11+
* Conscrypt acts as the security provider providing hybrid group `X25519MLKEM768`.
12+
13+
### Core Snapshot Artifacts
14+
The PQC verification depends on local SNAPSHOT builds of libraries containing our PQC enhancements:
15+
1. **`google-http-java-client`** (`pqc-support-conscrypt` branch): Enforces and wraps standard HTTP connections to prefer Conscrypt PQC sockets.
16+
2. **`gRPC-Java`** (`1.83.0-SNAPSHOT`): Enables Netty 4.2 support which negotiates hybrid key exchange by default.
17+
18+
---
19+
20+
## 2. Setting Up Showcase (Local TLS Server)
21+
22+
The `ITPqc` test suite runs integration tests against the local secure **GAPIC Showcase** server.
23+
24+
### Step 2.1: Download & Build Showcase with TLS Support
25+
Clone the showcase server and checkout the PQC TLS support branch:
26+
```shell
27+
git clone https://github.com/googleapis/gapic-showcase.git
28+
cd gapic-showcase
29+
git checkout feat-pqc-tls
30+
go build ./cmd/gapic-showcase
31+
```
32+
33+
### Step 2.2: Generate TLS Certificates
34+
Generate self-signed testing certificates using `openssl` (saved to `~/pqc-certs`):
35+
```shell
36+
mkdir -p ~/pqc-certs
37+
openssl req -x509 -newkey rsa:4096 -keyout ~/pqc-certs/server.key -out ~/pqc-certs/server.crt -sha256 -days 365 -nodes -subj "/CN=localhost"
38+
openssl x509 -outform pem -in ~/pqc-certs/server.crt -out ~/pqc-certs/ca.crt
39+
```
40+
41+
### Step 2.3: Run the Showcase Server
42+
Start the Showcase server in TLS mode using the generated certificate:
43+
```shell
44+
# Run on secure port 7470
45+
./gapic-showcase run \
46+
--tls-cert ~/pqc-certs/server.crt \
47+
--tls-key ~/pqc-certs/server.key \
48+
--port 7470
49+
```
50+
51+
---
52+
53+
## 3. Running Local Verification Tests
54+
55+
Use the helper script `build-with-local-http-client.sh` to automatically build/install `google-http-java-client` as a local snapshot, compile the monorepo, and execute Showcase PQC integration tests:
56+
57+
```shell
58+
# Set path to the google-http-java-client repository
59+
export HTTP_CLIENT_DIR=~/IdeaProjects/google-http-java-client
60+
61+
# Run the verification script
62+
./build-with-local-http-client.sh
63+
```
64+
65+
If successful, you will see `BUILD SUCCESS` and both `testGrpcPqc` and `testHttpJsonPqc` passing.
66+
67+
---
68+
69+
## 4. Standalone BigQuery PQC Tracing Sample
70+
71+
The class `BqPqcTest` runs a live connection to Google Cloud BigQuery, intercepts TLS sockets, and traces the negotiated curve/groups to verify `X25519MLKEM768` is used.
72+
73+
### Run with Maven
74+
To execute the BigQuery trace sample:
75+
76+
```shell
77+
cd pqc-verification
78+
79+
# Run using exec-maven-plugin
80+
mvn clean compile exec:java -Dproject.id="your-gcp-project-id"
81+
```
82+
83+
### Expected Output
84+
If Conscrypt is configured correctly and your environment supports PQC, you will see output tracing the handshake:
85+
```
86+
[DEBUG] Java Version: 17.0.19
87+
[DEBUG] Java Runtime: 17.0.19+10
88+
[DEBUG] Java VM : OpenJDK 64-Bit Server VM (17.0.19+10)
89+
[DEBUG] Conscrypt Version: 2.6.0
90+
Registered Conscrypt provider at position 1.
91+
Initializing BigQuery client for project: your-gcp-project-id
92+
Listing datasets using BigQuery Client with TLS tracing...
93+
[TLS TRACE] Handshake Completed
94+
Protocol : TLSv1.3
95+
CipherSuite: TLS_AES_128_GCM_SHA256
96+
Curve Name : X25519MLKEM768 (via Conscrypt OpenSSLSocketImpl.getCurveNameForTesting)
97+
Is PQC? : YES (Hybrid Post-Quantum)
98+
- my_dataset1
99+
- my_dataset2
100+
```

‎pqc-verification/pom.xml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Copyright 2026 Google LLC
4+
~
5+
~ Licensed under the Apache License, Version 2.0 (the "License");
6+
~ you may not use this file except in compliance with the License.
7+
~ You may obtain a copy of the License at
8+
~
9+
~ http://www.apache.org/licenses/LICENSE-2.0
10+
~
11+
~ Unless required by applicable law or agreed to in writing, software
12+
~ distributed under the License is distributed on an "AS IS" BASIS,
13+
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
~ See the License for the specific language governing permissions and
15+
~ limitations under the License.
16+
-->
17+
<project xmlns="http://maven.apache.org/POM/4.0.0"
18+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
19+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
20+
<modelVersion>4.0.0</modelVersion>
21+
22+
<groupId>com.google.cloud.pqc</groupId>
23+
<artifactId>pqc-verification</artifactId>
24+
<version>1.0-SNAPSHOT</version>
25+
26+
<properties>
27+
<maven.compiler.source>17</maven.compiler.source>
28+
<maven.compiler.target>17</maven.compiler.target>
29+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
30+
<bigquery.version>2.68.0-SNAPSHOT</bigquery.version>
31+
<http-client.version>2.1.2-SNAPSHOT</http-client.version>
32+
<conscrypt.version>2.6-alpha5</conscrypt.version>
33+
</properties>
34+
35+
<dependencies>
36+
<!-- BigQuery Java Client -->
37+
<dependency>
38+
<groupId>com.google.cloud</groupId>
39+
<artifactId>google-cloud-bigquery</artifactId>
40+
<version>${bigquery.version}</version>
41+
</dependency>
42+
43+
<!-- Force the PQC-modified google-http-client version -->
44+
<dependency>
45+
<groupId>com.google.http-client</groupId>
46+
<artifactId>google-http-client</artifactId>
47+
<version>${http-client.version}</version>
48+
</dependency>
49+
50+
<!-- Conscrypt Security Provider -->
51+
<dependency>
52+
<groupId>org.conscrypt</groupId>
53+
<artifactId>conscrypt-openjdk-uber</artifactId>
54+
<version>${conscrypt.version}</version>
55+
</dependency>
56+
</dependencies>
57+
58+
<build>
59+
<plugins>
60+
<!-- Exec Plugin to allow running the sample via mvn exec:java -->
61+
<plugin>
62+
<groupId>org.codehaus.mojo</groupId>
63+
<artifactId>exec-maven-plugin</artifactId>
64+
<version>3.1.0</version>
65+
<configuration>
66+
<mainClass>com.google.cloud.pqc.BqPqcTest</mainClass>
67+
</configuration>
68+
</plugin>
69+
</plugins>
70+
</build>
71+
</project>

0 commit comments

Comments
 (0)