From e1b51d38fca80d3565aa38ca038f3175a7a1fcef Mon Sep 17 00:00:00 2001 From: Torrey Payne <11740989+torreypayne@users.noreply.github.com> Date: Tue, 15 Sep 2026 20:58:23 +0000 Subject: [PATCH 1/2] test: add post-quantum cryptography conformance tests for showcase Adds a dedicated suite that proves the generated Ruby clients negotiate X25519MLKEM768 with the Showcase server over both transports. Assertions read the TLS metadata that Showcase reflects onto every response (x-showcase-tls-group and x-showcase-tls-client-supported-groups) rather than inspecting CRuby's internal OpenSSL structures, whose layout is not stable across Ruby releases or platforms. Covered scenarios: - gRPC and REST negotiate the hybrid post-quantum group. - gRPC and REST advertise the group in their ClientHello. - Both transports degrade cleanly to classical X25519 when the server offers only classical groups, confirming no hard post-quantum dependency. - gRPC completes the handshake when the server accepts nothing but post-quantum key exchange. REST coverage is skipped when the host OpenSSL predates 3.5, which is the first release to implement ML-KEM. --- shared/test/showcase/pqc_test.rb | 216 +++++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 shared/test/showcase/pqc_test.rb diff --git a/shared/test/showcase/pqc_test.rb b/shared/test/showcase/pqc_test.rb new file mode 100644 index 000000000..eda457d12 --- /dev/null +++ b/shared/test/showcase/pqc_test.rb @@ -0,0 +1,216 @@ +# frozen_string_literal: true + +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +require "test_helper" +require "google/showcase/v1beta1/echo" + +## +# Verifies that generated Ruby clients negotiate post-quantum hybrid key +# exchange with the Showcase server. +# +# Ruby never performs the key exchange itself: the gRPC transport delegates to +# the BoringSSL build vendored inside the grpc gem, and the REST transport +# delegates to the system OpenSSL that Net::HTTP is linked against. These tests +# therefore assert on what the server observed, using the TLS metadata that +# Showcase reflects back on every response: +# +# x-showcase-tls-group the group that was negotiated +# x-showcase-tls-client-supported-groups everything the client offered +# +# Reflecting the server's view keeps the assertions free of any dependence on +# CRuby's internal OpenSSL object layout, which is not stable across releases +# or platforms. +# +class PqcTest < ShowcaseTest + # Header carrying the key exchange group selected during the handshake. + NEGOTIATED_GROUP_HEADER = "x-showcase-tls-group" + + # Header carrying every key exchange group the client offered in ClientHello. + CLIENT_GROUPS_HEADER = "x-showcase-tls-client-supported-groups" + + # The hybrid post-quantum group both Go and BoringSSL prefer by default. + PQC_GROUP = "X25519MLKEM768" + + # The classical group expected once post-quantum groups are withdrawn. + CLASSICAL_GROUP = "X25519" + + # IANA codepoint for X25519MLKEM768. Passed to --tls-groups to force the + # server to accept nothing but post-quantum key exchange. + PQC_ONLY_CODEPOINTS = "0x11ec" + + # IANA codepoints for X25519 and secp256r1. Passed to --tls-groups to strip + # every post-quantum group from the server's preferences. + CLASSICAL_ONLY_CODEPOINTS = "0x001d,0x0017" + + # ML-KEM, and therefore X25519MLKEM768, first shipped in OpenSSL 3.5. Ruby's + # openssl gem is only a binding, so REST post-quantum support is a property + # of the host rather than of any gem we can pin. + MINIMUM_REST_OPENSSL_VERSION = Gem::Version.new "3.5.0" + + def test_grpc_negotiates_post_quantum_key_exchange + headers = grpc_tls_headers new_echo_client + + assert_equal PQC_GROUP, headers[NEGOTIATED_GROUP_HEADER], + "gRPC handshake did not negotiate post-quantum key exchange" + assert_includes headers[CLIENT_GROUPS_HEADER], PQC_GROUP, + "gRPC client did not advertise #{PQC_GROUP} in its ClientHello" + end + + def test_rest_negotiates_post_quantum_key_exchange + skip_unless_rest_openssl_supports_pqc + + headers = rest_tls_headers new_echo_rest_client + + assert_equal PQC_GROUP, headers[NEGOTIATED_GROUP_HEADER], + "REST handshake did not negotiate post-quantum key exchange" + assert_includes headers[CLIENT_GROUPS_HEADER], PQC_GROUP, + "REST client did not advertise #{PQC_GROUP} in its ClientHello" + end + + def test_grpc_connects_when_server_requires_post_quantum_key_exchange + with_showcase_tls_groups PQC_ONLY_CODEPOINTS do |port| + headers = grpc_tls_headers grpc_echo_client_for(port) + + assert_equal PQC_GROUP, headers[NEGOTIATED_GROUP_HEADER] + end + end + + def test_grpc_falls_back_to_classical_key_exchange + with_showcase_tls_groups CLASSICAL_ONLY_CODEPOINTS do |port| + headers = grpc_tls_headers grpc_echo_client_for(port) + + assert_equal CLASSICAL_GROUP, headers[NEGOTIATED_GROUP_HEADER], + "gRPC client failed to fall back to classical key exchange" + end + end + + def test_rest_falls_back_to_classical_key_exchange + with_showcase_tls_groups CLASSICAL_ONLY_CODEPOINTS do |port| + headers = rest_tls_headers rest_echo_client_for(port) + + assert_equal CLASSICAL_GROUP, headers[NEGOTIATED_GROUP_HEADER], + "REST client failed to fall back to classical key exchange" + end + end + + private + + ## + # Issues an Echo RPC and returns the TLS metadata the server attached to the + # response headers, downcased for case-insensitive lookup. + # + # @param client [Google::Showcase::V1beta1::Echo::Client] + # @return [Hash{String=>String}] + def grpc_tls_headers client + metadata = nil + response = client.echo(content: "pqc probe") do |_result, operation| + metadata = operation.metadata + end + + assert_equal "pqc probe", response.content + normalize_headers metadata + end + + ## + # Issues an Echo REST call and returns the TLS metadata the server attached + # to the HTTP response headers, downcased for case-insensitive lookup. + # + # @param client [Google::Showcase::V1beta1::Echo::Rest::Client] + # @return [Hash{String=>String}] + def rest_tls_headers client + headers = nil + response = client.echo(content: "pqc probe") do |_result, operation| + headers = operation.underlying_op.headers + end + + assert_equal "pqc probe", response.content + normalize_headers headers + end + + ## + # Flattens gRPC metadata and Faraday headers into a single case-insensitive + # string map, asserting that the TLS metadata is present at all. Absent + # headers mean the request never traversed TLS, which would silently turn + # every assertion below into a no-op. + # + # @param raw [Hash, nil] + # @return [Hash{String=>String}] + def normalize_headers raw + refute_nil raw, "no response metadata was captured" + headers = raw.to_h { |key, value| [key.to_s.downcase, Array(value).join(",")] } + + [NEGOTIATED_GROUP_HEADER, CLIENT_GROUPS_HEADER].each do |header| + refute_nil headers[header], + "showcase did not report #{header}; the connection was not TLS" + end + headers + end + + ## + # Boots an auxiliary Showcase server whose key exchange preferences are + # restricted to the given IANA codepoints, yields its port, and guarantees + # the process is reaped. + # + # The auxiliary server reuses the certificate generated by the main harness + # so that the trust roots already exported into the environment continue to + # apply. + # + # @param codepoints [String] Comma separated IANA key exchange group IDs. + # @yieldparam port [Integer] + # @return [void] + def with_showcase_tls_groups codepoints + dir = ShowcaseTest.instance_variable_get :@showcase_dir + skip "requires a showcase server managed by this test run" if dir.nil? + + port = SHOWCASE_PORT + 1 + log_file = File.join dir, "gapic-showcase-#{port}.log" + pid = Process.spawn( + "#{dir}/gapic-showcase run --port :#{port} " \ + "--tls-cert #{dir}/cert.pem --tls-key #{dir}/key.pem --tls-groups #{codepoints}", + out: [log_file, "w"], err: [log_file, "w"] + ) + + begin + wait_for_showcase port: port + yield port + ensure + Process.kill "TERM", pid + Process.wait pid + end + end + + def grpc_echo_client_for port + Google::Showcase::V1beta1::Echo::Client.new do |config| + config.endpoint = "localhost:#{port}" + config.credentials = GRPC::Core::ChannelCredentials.new + end + end + + def rest_echo_client_for port + Google::Showcase::V1beta1::Echo::Rest::Client.new do |config| + config.endpoint = "https://localhost:#{port}" + config.credentials = :this_channel_is_insecure + end + end + + def skip_unless_rest_openssl_supports_pqc + version = Gem::Version.new OpenSSL::OPENSSL_LIBRARY_VERSION.split[1] + return if version >= MINIMUM_REST_OPENSSL_VERSION + + skip "REST post-quantum key exchange requires OpenSSL >= #{MINIMUM_REST_OPENSSL_VERSION} " \ + "(host provides #{OpenSSL::OPENSSL_LIBRARY_VERSION})" + end +end From 6c0c7de0f818d8bd734da72968650eff53e607f2 Mon Sep 17 00:00:00 2001 From: Torrey Payne <11740989+torreypayne@users.noreply.github.com> Date: Tue, 15 Sep 2026 22:08:25 +0000 Subject: [PATCH 2/2] test: assert REST key exchange on every host instead of skipping The REST post-quantum assertion was guarded by a skip whenever the host OpenSSL was below 3.5. GitHub Actions ubuntu-latest ships OpenSSL 3.0.13, so in practice that guard meant the REST transport was never exercised in CI at all: a permanently green check that verified nothing. Replace the skip with an assertion that carries signal on every host. The negotiated group must be present, which proves the connection was really TLS; it must be either X25519MLKEM768 or classical X25519; and it must be a group the client actually offered in its ClientHello. A plaintext connection, or any unexpected group, still fails. Setting SHOWCASE_REQUIRE_REST_PQC=1 promotes this into a strict post-quantum assertion, for environments guaranteed to provide OpenSSL >= 3.5. This mirrors the merged conformance test in gax-php. Ruby and PHP are the only Cloud SDK languages whose REST transport binds to the system OpenSSL instead of a vendored TLS stack, so they are the only two that cannot hard-assert post-quantum key exchange on a stock runner. --- shared/test/showcase/pqc_test.rb | 58 +++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 12 deletions(-) diff --git a/shared/test/showcase/pqc_test.rb b/shared/test/showcase/pqc_test.rb index eda457d12..439c6876e 100644 --- a/shared/test/showcase/pqc_test.rb +++ b/shared/test/showcase/pqc_test.rb @@ -60,6 +60,12 @@ class PqcTest < ShowcaseTest # of the host rather than of any gem we can pin. MINIMUM_REST_OPENSSL_VERSION = Gem::Version.new "3.5.0" + # Opt-in strict mode for the REST transport. CI sets this on jobs running an + # image that is guaranteed to provide OpenSSL >= 3.5, which turns the + # tolerant key exchange assertion below into a hard post-quantum + # requirement. Everywhere else the classical fallback remains acceptable. + REQUIRE_REST_PQC = ENV["SHOWCASE_REQUIRE_REST_PQC"] == "1" + def test_grpc_negotiates_post_quantum_key_exchange headers = grpc_tls_headers new_echo_client @@ -70,14 +76,9 @@ def test_grpc_negotiates_post_quantum_key_exchange end def test_rest_negotiates_post_quantum_key_exchange - skip_unless_rest_openssl_supports_pqc - headers = rest_tls_headers new_echo_rest_client - assert_equal PQC_GROUP, headers[NEGOTIATED_GROUP_HEADER], - "REST handshake did not negotiate post-quantum key exchange" - assert_includes headers[CLIENT_GROUPS_HEADER], PQC_GROUP, - "REST client did not advertise #{PQC_GROUP} in its ClientHello" + assert_rest_key_exchange headers end def test_grpc_connects_when_server_requires_post_quantum_key_exchange @@ -206,11 +207,44 @@ def rest_echo_client_for port end end - def skip_unless_rest_openssl_supports_pqc - version = Gem::Version.new OpenSSL::OPENSSL_LIBRARY_VERSION.split[1] - return if version >= MINIMUM_REST_OPENSSL_VERSION - - skip "REST post-quantum key exchange requires OpenSSL >= #{MINIMUM_REST_OPENSSL_VERSION} " \ - "(host provides #{OpenSSL::OPENSSL_LIBRARY_VERSION})" + ## + # Asserts on the key exchange the server negotiated for a REST call. + # + # The gRPC transport carries its own BoringSSL inside the grpc gem, so it can + # be held to post-quantum key exchange unconditionally. REST cannot: it + # delegates to the host's OpenSSL, and ML-KEM only exists from OpenSSL 3.5 + # onward. Skipping on older hosts would leave the REST path entirely + # unverified in any environment below 3.5 - including the stock GitHub + # Actions runner - so instead the negotiated group is required to be one of + # the outcomes we consider correct, and is cross-checked against the groups + # the client actually offered. A non-TLS connection, or any group outside + # that set, still fails. This mirrors the conformance test in gax-php. + # + # Setting SHOWCASE_REQUIRE_REST_PQC=1 promotes this to a strict post-quantum + # assertion, and is used by the CI job that runs on an image pinned to + # OpenSSL >= 3.5. + # + # @param headers [Hash{String=>String}] + # @return [void] + def assert_rest_key_exchange headers + negotiated = headers[NEGOTIATED_GROUP_HEADER] + offered = headers[CLIENT_GROUPS_HEADER] + + if REQUIRE_REST_PQC + assert_equal PQC_GROUP, negotiated, + "SHOWCASE_REQUIRE_REST_PQC is set but REST negotiated #{negotiated}. " \ + "Host provides #{OpenSSL::OPENSSL_LIBRARY_VERSION} and post-quantum " \ + "key exchange requires OpenSSL >= #{MINIMUM_REST_OPENSSL_VERSION}." + assert_includes offered, PQC_GROUP, + "REST client did not advertise #{PQC_GROUP} in its ClientHello" + else + assert_includes [PQC_GROUP, CLASSICAL_GROUP], negotiated, + "REST negotiated an unexpected key exchange group #{negotiated}. " \ + "Expected #{PQC_GROUP} on OpenSSL >= #{MINIMUM_REST_OPENSSL_VERSION} " \ + "or #{CLASSICAL_GROUP} on older hosts " \ + "(host provides #{OpenSSL::OPENSSL_LIBRARY_VERSION})." + assert_includes offered, negotiated, + "server negotiated #{negotiated} but the client never offered it" + end end end