Skip to content

Commit e7d52be

Browse files
authored
docs: document Post-Quantum Cryptography (PQC) support and add TLS verification tests (#2713)
* docs: document Post-Quantum Cryptography (PQC) support and add TLS verification tests * test: make GODEBUG=tlsmlkem=0 PQC opt-out subtests non-vacuous on Go 1.26
1 parent 4ec343a commit e7d52be

4 files changed

Lines changed: 664 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ The Cloud SQL Auth Proxy has support for:
3131
- Metrics ([Cloud Monitoring][], [Cloud Trace][], and [Prometheus][])
3232
- [HTTP Healthchecks][health-check-example]
3333
- [Service account impersonation](#configuring-service-account-impersonation)
34+
- [Post-Quantum Cryptography (PQC)](#post-quantum-cryptography-pqc) over TLS 1.3
3435
- Separate Dialer functionality released as the [Cloud SQL Go Connector][go connector]
3536
- Configuration with [environment variables](#config-environment-variables)
3637
- Fully POSIX-compliant flags
@@ -689,6 +690,51 @@ when you want to proxy this traffic. Otherwise, it is optional. See
689690
[`http.ProxyFromEnvironment`](https://pkg.go.dev/net/http@go1.17.3#ProxyFromEnvironment)
690691
for possible values.
691692
693+
## Post-Quantum Cryptography (PQC)
694+
695+
The Cloud SQL Auth Proxy encrypts connections to Cloud SQL instances using TLS
696+
1.3 and negotiates the hybrid post-quantum key exchange **`X25519MLKEM768`**
697+
(IANA codepoint `0x11ec`) by default via Go's standard `crypto/tls` library.
698+
699+
### Supported Versions
700+
701+
- **Cloud SQL Auth Proxy v2 (`cloud-sql-proxy`)**: Enabled by default in
702+
official release binaries and container images starting with **`v2.15.2`**
703+
(built with Go 1.24+; upgrading to the latest `v2.27.x+` release is
704+
recommended).
705+
- **Cloud SQL Auth Proxy v1 (`cloud_sql_proxy`, maintenance)**: Enabled by
706+
default starting with **`v1.37.6`** (including **`v1.38.4+`**).
707+
- **Building from source**: Build with **Go 1.24 or later** (`go >= 1.24` in the
708+
main module's `go.mod`).
709+
- **Using `gcloud sql connect`**: `gcloud sql connect` establishes Second
710+
Generation connections through `cloud-sql-proxy` using either the Google Cloud
711+
SDK `cloud-sql-proxy` component (if installed) or `cloud-sql-proxy` on your
712+
system `PATH`. Run `gcloud components update` or ensure any standalone
713+
`cloud-sql-proxy` binary on `PATH` is `v2.15.2` or later.
714+
715+
### Automatic Fallback
716+
717+
No flags or configuration changes are required. Both hybrid `X25519MLKEM768` and
718+
classical `X25519` key shares are offered in the TLS 1.3 `ClientHello` (and Go
719+
1.26+ builds also advertise `SecP256r1MLKEM768` and `SecP384r1MLKEM1024` in
720+
`supported_groups`). If a Cloud SQL instance does not yet support hybrid PQC,
721+
the TLS 1.3 handshake automatically falls back to classical `X25519` without
722+
connection failures.
723+
724+
### Opting Out
725+
726+
If you need to disable post-quantum key exchange for troubleshooting or
727+
compatibility (for example, if a middlebox or firewall drops or resets TLS
728+
handshakes with larger `ClientHello` messages), set the Go runtime environment
729+
variable `GODEBUG=tlsmlkem=0`:
730+
731+
```shell
732+
GODEBUG=tlsmlkem=0 ./cloud-sql-proxy <INSTANCE_CONNECTION_NAME>
733+
```
734+
735+
When running in Docker, Kubernetes, or with `gcloud sql connect`, pass
736+
`GODEBUG=tlsmlkem=0` in the process or container environment.
737+
692738
## Support for Metrics and Tracing
693739
694740
The Proxy supports [Cloud Monitoring][], [Cloud Trace][], and [Prometheus][].

‎cmd/root.go‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,16 @@ Debug logging
305305
306306
./cloud-sql-proxy <INSTANCE_CONNECTION_NAME> --debug-logs
307307
308+
Post-Quantum Cryptography
309+
310+
By default, the Proxy negotiates the hybrid post-quantum key exchange
311+
X25519MLKEM768 over TLS 1.3 when built with Go 1.24 or later (v2.15.2+ and
312+
v1.37.6+), and automatically falls back to classical X25519 if the server does
313+
not support hybrid PQC. To disable post-quantum key exchange, set the
314+
environment variable GODEBUG=tlsmlkem=0:
315+
316+
GODEBUG=tlsmlkem=0 ./cloud-sql-proxy <INSTANCE_CONNECTION_NAME>
317+
308318
Waiting for Startup
309319
310320
See the wait subcommand's help for details.

‎docs/cmd/cloud-sql-proxy.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,16 @@ Debug logging
207207

208208
./cloud-sql-proxy <INSTANCE_CONNECTION_NAME> --debug-logs
209209

210+
Post-Quantum Cryptography
211+
212+
By default, the Proxy negotiates the hybrid post-quantum key exchange
213+
X25519MLKEM768 over TLS 1.3 when built with Go 1.24 or later (v2.15.2+ and
214+
v1.37.6+), and automatically falls back to classical X25519 if the server does
215+
not support hybrid PQC. To disable post-quantum key exchange, set the
216+
environment variable GODEBUG=tlsmlkem=0:
217+
218+
GODEBUG=tlsmlkem=0 ./cloud-sql-proxy <INSTANCE_CONNECTION_NAME>
219+
210220
Waiting for Startup
211221

212222
See the wait subcommand's help for details.

0 commit comments

Comments
 (0)