impl: add experimental client SSL certificate support

ci/cloudbuild/builds/lib/integration.sh

@@ -132,6 +132,21 @@ function integration::bazel_args() {
       "--test_env=GOOGLE_CLOUD_CPP_STORAGE_TEST_KEY_FILE_P12=${KEY_DIR}/${key_base}.p12"
     )
   fi
+
+  # Adds environment variables for SSL testing.
+  # Info on how to create/refresh these can be found at:
+  #    https://cloud.google.com/certificate-authority-service/docs/create-certificate
+  gcloud storage cp --quiet "${SECRETS_BUCKET}/client.crt" "${KEY_DIR}/client.crt" >/dev/null 2>&1 || true
+  gcloud storage cp --quiet "${SECRETS_BUCKET}/client.chain.crt" "${KEY_DIR}/client.chain.crt" >/dev/null 2>&1 || true
+  gcloud storage cp --quiet "${SECRETS_BUCKET}/client.private.pem" "${KEY_DIR}/client.private.pem" >/dev/null 2>&1 || true
+  if [[ -r "${KEY_DIR}/client.crt" ]] && [[ -r "${KEY_DIR}/client.chain.crt" ]] && [[ -r "${KEY_DIR}/client.private.pem" ]]; then
+    args+=(
+      "--test_env=GOOGLE_CLOUD_CPP_CLIENT_SSL_CERT_FILE=${KEY_DIR}/client.crt"
+      "--test_env=GOOGLE_CLOUD_CPP_CLIENT_SSL_CERT_CHAIN_FILE=${KEY_DIR}/client.chain.crt"
+      "--test_env=GOOGLE_CLOUD_CPP_CLIENT_SSL_KEY_FILE=${KEY_DIR}/client.private.pem"
+    )
+  fi
+
   printf "%s\n" "${args[@]}"
 }
 

google/cloud/credentials.h

@@ -17,6 +17,7 @@
 
 #include "google/cloud/common_options.h"
 #include "google/cloud/options.h"
+#include "google/cloud/ssl_certificate.h"
 #include "google/cloud/version.h"
 #include <chrono>
 #include <memory>
@@ -30,6 +31,22 @@ namespace internal {
 class CredentialsVisitor;
 }  // namespace internal
 
+namespace experimental {
+/**
+ * Represents a Client SSL certificate used in mTLS authentication.
+ *
+ * Providing this option enables both PEER and HOST verification.
+ *
+ * @note This option is currently experimental and only works with services
+ *     using JSON/HTTP transport.
+ *
+ * @note Requires libcurl v7.71.0 or later.
+ */
+struct ClientSslCertificateOption {
+  using Type = SslCertificate;
+};
+}  // namespace experimental
+
 /**
  * An opaque representation of the authentication configuration.
  *
@@ -433,7 +450,8 @@ struct CARootsFilePathOption {
 using UnifiedCredentialsOptionList =
     OptionList<AccessTokenLifetimeOption, CARootsFilePathOption,
                DelegatesOption, ScopesOption, LoggingComponentsOption,
-               UnifiedCredentialsOption>;
+               UnifiedCredentialsOption,
+               experimental::ClientSslCertificateOption>;
 
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace cloud

google/cloud/google_cloud_cpp_common.bzl

@@ -107,6 +107,7 @@ google_cloud_cpp_common_hdrs = [
     "project.h",
     "retry_policy.h",
     "rpc_metadata.h",
+    "ssl_certificate.h",
     "status.h",
     "status_or.h",
     "stream_range.h",

google/cloud/google_cloud_cpp_common.cmake

@@ -167,6 +167,7 @@ add_library(
     project.h
     retry_policy.h
     rpc_metadata.h
+    ssl_certificate.h
     status.cc
     status.h
     status_or.h

google/cloud/internal/curl_impl.cc

@@ -14,6 +14,7 @@
 
 #include "google/cloud/internal/curl_impl.h"
 #include "google/cloud/common_options.h"
+#include "google/cloud/credentials.h"
 #include "google/cloud/internal/absl_str_cat_quiet.h"
 #include "google/cloud/internal/absl_str_join_quiet.h"
 #include "google/cloud/internal/algorithm.h"
@@ -26,6 +27,7 @@
 #include "google/cloud/rest_options.h"
 #include "absl/strings/match.h"
 #include "absl/strings/strip.h"
+#include <curl/easy.h>
 #include <algorithm>
 #include <sstream>
 #include <thread>
@@ -198,6 +200,10 @@ CurlImpl::CurlImpl(CurlHandle handle,
   proxy_username_ = CurlOptProxyUsername(options);
   proxy_password_ = CurlOptProxyPassword(options);
 
+  if (options.has<experimental::ClientSslCertificateOption>()) {
+    client_ssl_cert_ = options.get<experimental::ClientSslCertificateOption>();
+  }
+
   interface_ = CurlOptInterface(options);
 }
 
@@ -327,6 +333,44 @@ Status CurlImpl::MakeRequest(HttpMethod method, RestContext& context,
     if (!status.ok()) return OnTransferError(context, std::move(status));
   }
 
+  if (client_ssl_cert_.has_value()) {
+#if CURL_AT_LEAST_VERSION(7, 71, 0)
+    status = handle_.SetOption(CURLOPT_SSL_VERIFYPEER, 1L);
+    if (!status.ok()) return OnTransferError(context, std::move(status));
+    status = handle_.SetOption(CURLOPT_SSL_VERIFYHOST, 2L);
+    if (!status.ok()) return OnTransferError(context, std::move(status));
+
+    status = handle_.SetOption(CURLOPT_SSLCERTTYPE,
+                               experimental::SslCertificate::ToString(
+                                   client_ssl_cert_->ssl_certificate_type())
+                                   .c_str());
+    if (!status.ok()) return OnTransferError(context, std::move(status));
+
+    struct curl_blob ssl_cert_blob;
+    ssl_cert_blob.data =
+        const_cast<char*>(client_ssl_cert_->ssl_certificate().data());
+    ssl_cert_blob.len = client_ssl_cert_->ssl_certificate().length();
+    ssl_cert_blob.flags = CURL_BLOB_COPY;
+    status = handle_.SetOption(CURLOPT_SSLCERT_BLOB, &ssl_cert_blob);
+    if (!status.ok()) return OnTransferError(context, std::move(status));
+
+    struct curl_blob ssl_key_blob;
+    ssl_key_blob.data =
+        const_cast<char*>(client_ssl_cert_->ssl_private_key().data());
+    ssl_key_blob.len = client_ssl_cert_->ssl_private_key().length();
+    ssl_key_blob.flags = CURL_BLOB_COPY;
+    status = handle_.SetOption(CURLOPT_SSLKEY_BLOB, &ssl_key_blob);
+    if (!status.ok()) return OnTransferError(context, std::move(status));
+#else
+    return OnTransferError(
+        context,
+        internal::InvalidArgumentError(
+            "libcurl 7.71.0 or higher required to use ClientSslCertificate",
+            GCP_ERROR_INFO().WithMetadata("current_libcurl_version",
+                                          LIBCURL_VERSION)));
+#endif
+  }
+
   if (method == HttpMethod::kGet) {
     status = handle_.SetOption(CURLOPT_NOPROGRESS, 1L);
     if (!status.ok()) return OnTransferError(context, std::move(status));

google/cloud/internal/curl_impl.h

@@ -23,6 +23,7 @@
 #include "google/cloud/internal/rest_request.h"
 #include "google/cloud/internal/rest_response.h"
 #include "google/cloud/options.h"
+#include "google/cloud/ssl_certificate.h"
 #include "google/cloud/status_or.h"
 #include "google/cloud/version.h"
 #include "absl/types/optional.h"
@@ -143,6 +144,8 @@ class CurlImpl {
   absl::optional<std::string> proxy_username_;
   absl::optional<std::string> proxy_password_;
 
+  absl::optional<experimental::SslCertificate> client_ssl_cert_ = absl::nullopt;
+
   absl::optional<std::string> interface_;
 
   CurlReceivedHeaders received_headers_;

google/cloud/ssl_certificate.h

@@ -0,0 +1,79 @@
+// Copyright 2025 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.
+
+#ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SSL_CERTIFICATE_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SSL_CERTIFICATE_H
+
+#include "google/cloud/version.h"
+#include <string>
+
+namespace google {
+namespace cloud {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+namespace experimental {
+
+/**
+ * Represents an SSL certificate used in TLS authentication.
+ */
+class SslCertificate {
+ public:
+  enum class SslCertificateType { kPEM, kDER, kP12 };
+
+  /// Creates and empty certificate.
+  SslCertificate() = default;
+
+  /// Creates a PEM certificate from the values provided.
+  SslCertificate(std::string ssl_certificate, std::string ssl_private_key)
+      : ssl_certificate_(std::move(ssl_certificate)),
+        ssl_private_key_(std::move(ssl_private_key)) {}
+
+  /// Creates a user specified type of certificate from the values provided.
+  SslCertificate(std::string ssl_certificate, std::string ssl_private_key,
+                 SslCertificateType ssl_certificate_type)
+      : ssl_certificate_(std::move(ssl_certificate)),
+        ssl_private_key_(std::move(ssl_private_key)),
+        ssl_certificate_type_(ssl_certificate_type) {}
+
+  std::string const& ssl_certificate() const { return ssl_certificate_; }
+
+  std::string const& ssl_private_key() const { return ssl_private_key_; }
+
+  SslCertificateType ssl_certificate_type() const {
+    return ssl_certificate_type_;
+  }
+
+  static std::string ToString(SslCertificateType type) {
+    switch (type) {
+      case SslCertificateType::kPEM:
+        return "PEM";
+      case SslCertificateType::kDER:
+        return "DER";
+      case SslCertificateType::kP12:
+        return "P12";
+    }
+    return {};
+  }
+
+ private:
+  std::string ssl_certificate_;
+  std::string ssl_private_key_;
+  SslCertificateType ssl_certificate_type_ = SslCertificateType::kPEM;
+};
+
+}  // namespace experimental
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SSL_CERTIFICATE_H

google/cloud/storage/tests/CMakeLists.txt

@@ -72,8 +72,11 @@ set(storage_client_integration_tests
     tracing_integration_test.cc)
 set(storage_client_integration_tests_production
     # cmake-format: sort
-    alternative_endpoint_integration_test.cc key_file_integration_test.cc
-    signed_url_integration_test.cc unified_credentials_integration_test.cc)
+    alternative_endpoint_integration_test.cc
+    key_file_integration_test.cc
+    mtls_object_basic_crud_integration_test.cc
+    signed_url_integration_test.cc
+    unified_credentials_integration_test.cc)
 list(APPEND storage_client_integration_tests
      ${storage_client_integration_tests_production})
 list(SORT storage_client_integration_tests)