Responding to PR comments and adding a new exception type.

Author: aeitzman

oauth2_http/java/com/google/auth/mtls/CertificateSourceUnavailableException.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2025, Google Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *    * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *    * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *
+ *    * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package com.google.auth.mtls;
+
+import java.io.IOException;
+
+/**
+ * This exception is thrown by certificate providers in the Google auth library when the certificate
+ * source is unavailable. This means that the transport layer should move on to the next certificate
+ * source provider type.
+ */
+public class CertificateSourceUnavailableException extends IOException {
+
+  /**
+   * Constructor with a message and throwable cause.
+   *
+   * @param message The detail message (which is saved for later retrieval by the {@link
+   *     #getMessage()} method)
+   * @param cause The cause (which is saved for later retrieval by the {@link #getCause()} method).
+   *     (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
+   */
+  public CertificateSourceUnavailableException(String message, Throwable cause) {
+    super(message, cause);
+  }
+
+  /**
+   * Constructor with a throwable cause.
+   *
+   * @param cause The cause (which is saved for later retrieval by the {@link #getCause()} method).
+   *     (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
+   */
+  public CertificateSourceUnavailableException(Throwable cause) {
+    super(cause);
+  }
+
+  /**
+   * Constructor with a message.
+   *
+   * @param message The detail message (which is saved for later retrieval by the {@link
+   *     #getMessage()} method)
+   */
+  public CertificateSourceUnavailableException(String message) {
+    super(message);
+  }
+}

oauth2_http/java/com/google/auth/mtls/WorkloadCertificateConfiguration.java

@@ -35,6 +35,7 @@
 import com.google.api.client.json.JsonFactory;
 import com.google.api.client.json.JsonObjectParser;
 import com.google.api.client.json.gson.GsonFactory;
+import com.google.common.base.Preconditions;
 import com.google.common.base.Strings;
 import java.io.IOException;
 import java.io.InputStream;
@@ -64,9 +65,7 @@ String getPrivateKeyPath() {
 
   static WorkloadCertificateConfiguration fromCertificateConfigurationStream(
       InputStream certConfigStream) throws IOException {
-    if (certConfigStream == null) {
-      throw new IllegalArgumentException("certConfigStream must not be null.");
-    }
+    Preconditions.checkNotNull(certConfigStream);
 
     GenericJson fileContents =
         parser.parseAndClose(certConfigStream, StandardCharsets.UTF_8, GenericJson.class);
@@ -79,7 +78,7 @@ static WorkloadCertificateConfiguration fromCertificateConfigurationStream(
 
     Map<String, Object> workloadConfig = (Map<String, Object>) certConfigs.get("workload");
     if (workloadConfig == null) {
-      throw new IllegalArgumentException(
+      throw new CertificateSourceUnavailableException(
           "A workload certificate configuration must be provided in the cert_configs object.");
     }
 

oauth2_http/java/com/google/auth/mtls/X509Provider.java

@@ -32,6 +32,7 @@
 package com.google.auth.mtls;
 
 import com.google.api.client.util.SecurityUtils;
+import com.google.common.base.Strings;
 import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileNotFoundException;
@@ -41,17 +42,35 @@
 import java.security.KeyStore;
 import java.util.Locale;
 
+/**
+ * This class provides certificate key stores to the Google Auth library transport layer via
+ * certificate configuration files. This is only meant to be used internally to Google Cloud
+ * libraries, and the public facing methods may be changed without notice, and have no guarantee of
+ * backwards compatability.
+ */
 public class X509Provider {
   static final String CERTIFICATE_CONFIGURATION_ENV_VARIABLE = "GOOGLE_API_CERTIFICATE_CONFIG";
   static final String WELL_KNOWN_CERTIFICATE_CONFIG_FILE = "certificate_config.json";
   static final String CLOUDSDK_CONFIG_DIRECTORY = "gcloud";
 
   private String certConfigPathOverride;
 
+  /**
+   * Creates an X509 provider with an override path for the certificate configuration, bypassing the
+   * normal checks for the well known certificate configuration file path and environment variable.
+   * This is meant for internal Google Cloud usage and behavior may be changed without warning.
+   *
+   * @param certConfigPathOverride the path to read the certificate configuration from.
+   */
   public X509Provider(String certConfigPathOverride) {
     this.certConfigPathOverride = certConfigPathOverride;
   }
 
+  /**
+   * Creates a new X.509 provider that will check the environment variable path and the well known
+   * Gcloud certificate configuration location. This is meant for internal Google Cloud usage and
+   * behavior may be changed without warning.
+   */
   public X509Provider() {
     this(null);
   }
@@ -76,20 +95,24 @@ public KeyStore getKeyStore() throws IOException {
 
     InputStream certStream = null;
     InputStream privateKeyStream = null;
+    SequenceInputStream certAndPrivateKeyStream = null;
     try {
       // Read the certificate and private key file paths into separate streams.
       File certFile = new File(workloadCertConfig.getCertPath());
       File privateKeyFile = new File(workloadCertConfig.getPrivateKeyPath());
-      certStream = readStream(certFile);
-      privateKeyStream = readStream(privateKeyFile);
+      certStream = createInputStream(certFile);
+      privateKeyStream = createInputStream(privateKeyFile);
 
       // Merge the two streams into a single stream.
-      SequenceInputStream certAndPrivateKeyStream =
-          new SequenceInputStream(certStream, privateKeyStream);
+      certAndPrivateKeyStream = new SequenceInputStream(certStream, privateKeyStream);
 
       // Build a key store using the combined stream.
       return SecurityUtils.createMtlsKeyStore(certAndPrivateKeyStream);
+    } catch (CertificateSourceUnavailableException e) {
+      // Throw the CertificateSourceUnavailableException without wrapping.
+      throw e;
     } catch (Exception e) {
+      // Wrap all other exception types to an IOException.
       throw new IOException(e);
     } finally {
       if (certStream != null) {
@@ -98,6 +121,9 @@ public KeyStore getKeyStore() throws IOException {
       if (privateKeyStream != null) {
         privateKeyStream.close();
       }
+      if (certAndPrivateKeyStream != null) {
+        certAndPrivateKeyStream.close();
+      }
     }
   }
 
@@ -108,7 +134,7 @@ private WorkloadCertificateConfiguration getWorkloadCertificateConfiguration()
       certConfig = new File(certConfigPathOverride);
     } else {
       String envCredentialsPath = getEnv(CERTIFICATE_CONFIGURATION_ENV_VARIABLE);
-      if (envCredentialsPath != null && !envCredentialsPath.isEmpty()) {
+      if (!Strings.isNullOrEmpty(envCredentialsPath)) {
         certConfig = new File(envCredentialsPath);
       } else {
         certConfig = getWellKnownCertificateConfigFile();
@@ -120,13 +146,13 @@ private WorkloadCertificateConfiguration getWorkloadCertificateConfiguration()
         // Path will be put in the message from the catch block below
         throw new IOException("File does not exist.");
       }
-      certConfigStream = readStream(certConfig);
+      certConfigStream = createInputStream(certConfig);
       return WorkloadCertificateConfiguration.fromCertificateConfigurationStream(certConfigStream);
     } catch (Exception e) {
       // Although it is also the cause, the message of the caught exception can have very
       // important information for diagnosing errors, so include its message in the
       // outer exception message also.
-      throw new IOException(
+      throw new CertificateSourceUnavailableException(
           String.format(
               "Error reading certificate configuration file value '%s': %s",
               certConfig.getPath(), e.getMessage()),
@@ -145,7 +171,7 @@ boolean isFile(File file) {
     return file.isFile();
   }
 
-  InputStream readStream(File file) throws FileNotFoundException {
+  InputStream createInputStream(File file) throws FileNotFoundException {
     return new FileInputStream(file);
   }
 

oauth2_http/javatests/com/google/auth/mtls/WorkloadCertificateConfigurationTest.java

@@ -31,10 +31,8 @@
 
 package com.google.auth.mtls;
 
-import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertTrue;
-import static org.junit.Assert.fail;
 
 import com.google.api.client.json.GenericJson;
 import com.google.auth.TestUtils;
@@ -63,8 +61,15 @@ public void workloadCertificateConfig_fromStreamMissingCertPath_Fails() throws I
     InputStream configStream = writeWorkloadCertificateConfigStream(certPath, privateKeyPath);
 
     IllegalArgumentException exception =
-        Assert.assertThrows(IllegalArgumentException.class, () -> WorkloadCertificateConfiguration.fromCertificateConfigurationStream(configStream));
-    assertTrue(exception.getMessage().contains("The cert_path field must be provided in the workload certificate configuration."));
+        Assert.assertThrows(
+            IllegalArgumentException.class,
+            () ->
+                WorkloadCertificateConfiguration.fromCertificateConfigurationStream(configStream));
+    assertTrue(
+        exception
+            .getMessage()
+            .contains(
+                "The cert_path field must be provided in the workload certificate configuration."));
   }
 
   @Test
@@ -74,8 +79,15 @@ public void workloadCertificateConfig_fromStreamMissingPrivateKeyPath_Fails() th
     InputStream configStream = writeWorkloadCertificateConfigStream(certPath, privateKeyPath);
 
     IllegalArgumentException exception =
-        Assert.assertThrows(IllegalArgumentException.class, () -> WorkloadCertificateConfiguration.fromCertificateConfigurationStream(configStream));
-    assertTrue(exception.getMessage().contains("The key_path field must be provided in the workload certificate configuration."));
+        Assert.assertThrows(
+            IllegalArgumentException.class,
+            () ->
+                WorkloadCertificateConfiguration.fromCertificateConfigurationStream(configStream));
+    assertTrue(
+        exception
+            .getMessage()
+            .contains(
+                "The key_path field must be provided in the workload certificate configuration."));
   }
 
   @Test
@@ -84,9 +96,16 @@ public void workloadCertificateConfig_fromStreamMissingWorkload_Fails() throws I
     json.put("cert_configs", new GenericJson());
     InputStream configStream = TestUtils.jsonToInputStream(json);
 
-    IllegalArgumentException exception =
-        Assert.assertThrows(IllegalArgumentException.class, () -> WorkloadCertificateConfiguration.fromCertificateConfigurationStream(configStream));
-    assertTrue(exception.getMessage().contains("A workload certificate configuration must be provided in the cert_configs object."));
+    CertificateSourceUnavailableException exception =
+        Assert.assertThrows(
+            CertificateSourceUnavailableException.class,
+            () ->
+                WorkloadCertificateConfiguration.fromCertificateConfigurationStream(configStream));
+    assertTrue(
+        exception
+            .getMessage()
+            .contains(
+                "A workload certificate configuration must be provided in the cert_configs object."));
   }
 
   @Test
@@ -95,8 +114,15 @@ public void workloadCertificateConfig_fromStreamMissingCertConfig_Fails() throws
     InputStream configStream = TestUtils.jsonToInputStream(json);
 
     IllegalArgumentException exception =
-        Assert.assertThrows(IllegalArgumentException.class, () -> WorkloadCertificateConfiguration.fromCertificateConfigurationStream(configStream));
-    assertTrue(exception.getMessage().contains("The cert_configs object must be provided in the certificate configuration file."));
+        Assert.assertThrows(
+            IllegalArgumentException.class,
+            () ->
+                WorkloadCertificateConfiguration.fromCertificateConfigurationStream(configStream));
+    assertTrue(
+        exception
+            .getMessage()
+            .contains(
+                "The cert_configs object must be provided in the certificate configuration file."));
   }
 
   static InputStream writeWorkloadCertificateConfigStream(String certPath, String privateKeyPath)

oauth2_http/javatests/com/google/auth/mtls/X509ProviderTest.java

@@ -32,7 +32,6 @@
 package com.google.auth.mtls;
 
 import static org.junit.Assert.assertTrue;
-import static org.junit.Assert.fail;
 
 import java.io.ByteArrayInputStream;
 import java.io.File;
@@ -94,8 +93,9 @@ public void x509Provider_fileDoesntExist_throws() {
             "Error reading certificate configuration file value '%s': File does not exist.",
             certConfigPath);
 
-    IOException exception =
-        Assert.assertThrows(IOException.class, () -> testProvider.getKeyStore());
+    CertificateSourceUnavailableException exception =
+        Assert.assertThrows(
+            CertificateSourceUnavailableException.class, () -> testProvider.getKeyStore());
     assertTrue(exception.getMessage().contains(expectedErrorMessage));
   }
 
@@ -236,7 +236,7 @@ boolean isFile(File file) {
     }
 
     @Override
-    InputStream readStream(File file) throws FileNotFoundException {
+    InputStream createInputStream(File file) throws FileNotFoundException {
       InputStream stream = files.get(file.getPath());
       if (stream == null) {
         throw new FileNotFoundException(file.getPath());