From af2d9caf3f950830694d2ed2a532d736826aadd4 Mon Sep 17 00:00:00 2001 From: Zhen Lian Date: Thu, 5 Mar 2020 10:52:26 -0800 Subject: [PATCH] make class comments to JavaDoc comments --- .../netty/ConfigurableX509TrustManager.java | 28 ++++++--- .../main/java/io/grpc/netty/TlsOptions.java | 60 +++++++++++++------ 2 files changed, 62 insertions(+), 26 deletions(-) diff --git a/netty/src/main/java/io/grpc/netty/ConfigurableX509TrustManager.java b/netty/src/main/java/io/grpc/netty/ConfigurableX509TrustManager.java index 35c7950e0a38..ebb0ae4f9c93 100644 --- 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 index 30b4eb6cb112..891952e61740 100644 --- 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; -} \ No newline at end of file +}