feat(mtls): Update code comments

andyrzhao · andyrzhao · commit 7a2b2ce62a9a · 2025-04-09T15:18:13.000-07:00
diff --git a/oauth2_http/java/com/google/auth/mtls/CertificateSourceUnavailableException.java b/oauth2_http/java/com/google/auth/mtls/CertificateSourceUnavailableException.java
@@ -1,18 +1,17 @@
 /*
- * Copyright 2025, Google Inc. All rights reserved.
+ * Copyright 2025 Google LLC
  *
  * 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
+ *     * 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
+ *     * 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
+ *     * Neither the name of Google LLC nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
diff --git a/oauth2_http/java/com/google/auth/mtls/DefaultMtlsProviderFactory.java b/oauth2_http/java/com/google/auth/mtls/DefaultMtlsProviderFactory.java
@@ -1,18 +1,17 @@
 /*
- * Copyright 2025, Google Inc. All rights reserved.
+ * Copyright 2025 Google LLC
  *
  * 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
+ *     * 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
+ *     * 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
+ *     * Neither the name of Google LLC nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
diff --git a/oauth2_http/java/com/google/auth/mtls/MtlsProvider.java b/oauth2_http/java/com/google/auth/mtls/MtlsProvider.java
@@ -1,18 +1,17 @@
 /*
- * Copyright 2025, Google Inc. All rights reserved.
+ * Copyright 2025 Google LLC
  *
  * 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
+ *     * 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
+ *     * 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
+ *     * Neither the name of Google LLC nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
@@ -34,6 +33,13 @@
 import java.io.IOException;
 import java.security.KeyStore;
 
+/**
+ * MtlsProvider is used by the Gax library for configuring mutual TLS in the HTTP and GRPC transport
+ * layer. The source of the client certificate is up to the implementation.
+ *
+ * <p>Note: This interface will replace the identically named "MtlsProvider" implementation in the
+ * Gax library. The Gax library version of MtlsProvider will be marked as deprecated.
+ */
 public interface MtlsProvider {
   /** Returns the mutual TLS key store. */
   KeyStore getKeyStore() throws IOException;
diff --git a/oauth2_http/java/com/google/auth/mtls/SecureConnectProvider.java b/oauth2_http/java/com/google/auth/mtls/SecureConnectProvider.java
@@ -1,18 +1,17 @@
 /*
- * Copyright 2025, Google Inc. All rights reserved.
+ * Copyright 2025 Google LLC
  *
  * 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
+ *     * 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
+ *     * 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
+ *     * Neither the name of Google LLC nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
@@ -45,8 +44,20 @@
 import java.util.List;
 
 /**
- * Provider class for mutual TLS. It is used to configure the mutual TLS in the transport with the
- * default client certificate on device.
+ * This class implements {@link MtlsProvider} for the Google Auth library transport layer via {@link
+ * ContextAwareMetadataJson}. This is only meant to be used internally by Google Cloud libraries,
+ * and the public facing methods may be changed without notice, and have no guarantee of backwards
+ * compatability.
+ *
+ * <p>Note: This implementation is derived from the existing "MtlsProvider" found in the Gax
+ * library, with two notable differences: 1) All logic associated with parsing environment variables
+ * related to "mTLS usage" are omitted - a separate helper class will be introduced in the Gax
+ * library to serve this purpose. 2) getKeyStore throws {@link
+ * com.google.auth.mtls.CertificateSourceUnavailableException} instead of returning "null" if this
+ * cert source is not available on the device.
+ *
+ * <p>Additionally, this implementation will replace the existing "MtlsProvider" in the Gax library.
+ * The Gax library version of MtlsProvider will be marked as deprecated.
  */
 public class SecureConnectProvider implements MtlsProvider {
   interface ProcessProvider {
diff --git a/oauth2_http/java/com/google/auth/mtls/WorkloadCertificateConfiguration.java b/oauth2_http/java/com/google/auth/mtls/WorkloadCertificateConfiguration.java
@@ -1,18 +1,17 @@
 /*
- * Copyright 2025, Google Inc. All rights reserved.
+ * Copyright 2025 Google LLC
  *
  * 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
+ *     * 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
+ *     * 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
+ *     * Neither the name of Google LLC nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
diff --git a/oauth2_http/java/com/google/auth/mtls/X509Provider.java b/oauth2_http/java/com/google/auth/mtls/X509Provider.java
@@ -1,18 +1,17 @@
 /*
- * Copyright 2025, Google Inc. All rights reserved.
+ * Copyright 2025 Google LLC
  *
  * 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
+ *     * 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
+ *     * 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
+ *     * Neither the name of Google LLC nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
@@ -43,8 +42,8 @@
 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
+ * This class implements {@link MtlsProvider} for the Google Auth library transport layer via {@link
+ * WorkloadCertificateConfiguration}. This is only meant to be used internally by Google Cloud
  * libraries, and the public facing methods may be changed without notice, and have no guarantee of
  * backwards compatability.
  */
