make class comments to JavaDoc comments

grpc · Mar 5, 2020 · af2d9ca · af2d9ca
1 parent 0914bcb
commit af2d9ca
Show file tree

Hide file tree

Showing 2 changed files with 62 additions and 26 deletions.
diff --git a/netty/src/main/java/io/grpc/netty/ConfigurableX509TrustManager.java b/netty/src/main/java/io/grpc/netty/ConfigurableX509TrustManager.java
@@ -16,6 +16,8 @@
 
 package io.grpc.netty;
 
+import static com.google.common.base.Preconditions.checkNotNull;
+
 import io.grpc.netty.TlsOptions.VerificationAuthType;
 import java.net.Socket;
 import java.security.KeyStore;
@@ -27,12 +29,17 @@
 import javax.net.ssl.TrustManagerFactory;
 import javax.net.ssl.X509ExtendedTrustManager;
 
+/**
+ * ConfigurableX509TrustManager is a highly configurable class that allows users choose different
+ * level of peer checking mechanisms, as well as some customized check. It could also be used to
+ * reload trust certificate bundle client/server uses.
+ */
 public class ConfigurableX509TrustManager extends X509ExtendedTrustManager {
 
   private TlsOptions tlsOptions;
 
   public ConfigurableX509TrustManager(TlsOptions tlsOptions) {
-    this.tlsOptions = tlsOptions;
+    this.tlsOptions = checkNotNull(tlsOptions, "tlsOptions");
   }
 
   @Override
@@ -83,7 +90,7 @@ private void checkTrusted(X509Certificate[] x509Certificates, String s, SSLEngin
         || authType == VerificationAuthType.CertificateVerification) {
       if (x509Certificates == null || x509Certificates.length == 0) {
         throw new CertificateException(
-            "Client side requires certificate but got null or empty certificates");
+            "Want certificate verification but got null or empty certificates");
       }
       KeyStore ks;
       try {
@@ -114,11 +121,18 @@ private void checkTrusted(X509Certificate[] x509Certificates, String s, SSLEngin
             + e.getMessage());
       }
       if (isClient) {
-        String algorithm = authType == VerificationAuthType.CertificateAndHostNameVerification
-            ? "HTTPS" : "";
-        SSLParameters sslParams = sslEngine.getSSLParameters();
-        sslParams.setEndpointIdentificationAlgorithm(algorithm);
-        sslEngine.setSSLParameters(sslParams);
+        if (authType == VerificationAuthType.CertificateAndHostNameVerification
+            && (sslEngine == null || sslEngine.getSSLParameters() == null)) {
+          throw new CertificateException(
+              "SSLEngine or SSLParameters is null. Couldn't check host name");
+        }
+        if (sslEngine != null && sslEngine.getSSLParameters() != null) {
+          String algorithm = authType == VerificationAuthType.CertificateAndHostNameVerification
+              ? "HTTPS" : "";
+          SSLParameters sslParams = sslEngine.getSSLParameters();
+          sslParams.setEndpointIdentificationAlgorithm(algorithm);
+          sslEngine.setSSLParameters(sslParams);
+        }
         delegateManager.checkServerTrusted(x509Certificates, s, sslEngine);
       } else {
         delegateManager.checkClientTrusted(x509Certificates, s, sslEngine);

diff --git a/netty/src/main/java/io/grpc/netty/TlsOptions.java b/netty/src/main/java/io/grpc/netty/TlsOptions.java
@@ -20,26 +20,36 @@
 import java.security.cert.X509Certificate;
 import javax.net.ssl.SSLEngine;
 
-// TlsOptions contains different options users could choose. In a nutshell, it provides three main
-// features users could customize:
-// 1. choose different levels of peer verification by specifying |VerificationAuthType|
-// 2. provide custom peer verification check by inheriting |verifyPeerCertificate|
-// 3. change the trust CA certificate bundle by inheriting |getTrustedCerts|
+/**
+ * TlsOptions contains different options users could choose. In a nutshell, it provides three main
+ * features users could customize:
+ * 1. choose different levels of peer verification by specifying |VerificationAuthType|
+ * 2. provide custom peer verification check by inheriting |verifyPeerCertificate|
+ * 3. change the trust CA certificate bundle by inheriting |getTrustedCerts|
+ */
 public abstract class TlsOptions {
-  // VerificationAuthType contains set of verification levels users can choose to customize
-  // their checks against its peer.
-  // Note we don't have hostname check on server side. Choosing CertificateAndHostNameVerification
-  // has the same effect as choosing CertificateVerification on server side, in terms of peer
-  // endpoint check.
+  /**
+   * VerificationAuthType contains set of verification levels users can choose to customize
+   * their checks against its peer.
+   * Note we don't have hostname check on server side. Choosing CertificateAndHostNameVerification
+   * has the same effect as choosing CertificateVerification on server side, in terms of peer
+   * endpoint check.
+   */
   public enum VerificationAuthType {
-    // Default option: performs certificate verification and hostname verification.
+    /**
+     * Default option: performs certificate verification and hostname verification.
+     */
     CertificateAndHostNameVerification,
-    // Performs certificate verification, but skips hostname verification.
-    // Users are responsible for verifying peer's identity via custom check callback.
+    /**
+     * Performs certificate verification, but skips hostname verification.
+     * Users are responsible for verifying peer's identity via custom check callback.
+     */
     CertificateVerification,
-    // Skips both certificate and hostname verification.
-    // Users are responsible for verifying peer's identity and peer's certificate via custom
-    // check callback.
+    /**
+     * Skips both certificate and hostname verification.
+     * Users are responsible for verifying peer's identity and peer's certificate via custom
+     * check callback.
+     */
     SkipAllVerification,
   }
 
@@ -53,10 +63,22 @@ public VerificationAuthType getVerificationAuthType() {
     return this.verificationType;
   }
 
-  // used to perform custom peer authorization checking
+  /**
+   * sub-classes extend this function to perform custom peer identity checking.
+   * @param peerCertChain the certificate chain sent from the peer
+   * @param authType the key exchange algorithm used
+   * @param engine the engine used for this connection. This parameter can be null, which indicates
+   *     that implementations need not check the ssl parameters
+   * @throws Exception exception thrown when performing custom peer identity check
+   */
   abstract void verifyPeerCertificate(X509Certificate[] peerCertChain, String authType,
       SSLEngine engine) throws Exception;
 
-  // used to perform trust CA certificates reloading
+  /**
+   * sub-classes extend this function to perform trust certificate bundle reloading.
+   * @return A KeyStore containing the trust certificate bundle that will be used for the following
+   *     connections.
+   * @throws Exception exception thrown when performing trust certificate bundle reloading
+   */
   abstract KeyStore getTrustedCerts() throws Exception;
-}
+}