Package io.grpc.util

Class AdvancedTlsX509TrustManager

java.lang.Object

javax.net.ssl.X509ExtendedTrustManager

io.grpc.util.AdvancedTlsX509TrustManager

All Implemented Interfaces:

javax.net.ssl.TrustManager, javax.net.ssl.X509TrustManager

public final class AdvancedTlsX509TrustManager
extends javax.net.ssl.X509ExtendedTrustManager

AdvancedTlsX509TrustManager is an X509ExtendedTrustManager that allows users to configure advanced TLS features, such as root certificate reloading and peer cert custom verification. The basic instantiation pattern is new Builder().build().useSystemDefaultTrustCerts();

For Android users: this class is only supported in API level 24 and above.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AdvancedTlsX509TrustManager.Builder	Builds a new AdvancedTlsX509TrustManager.
static interface	AdvancedTlsX509TrustManager.Closeable
private class	AdvancedTlsX509TrustManager.LoadFilePathExecution
static interface	AdvancedTlsX509TrustManager.SslSocketAndEnginePeerVerifier
static class	AdvancedTlsX509TrustManager.Verification	The verification mode when authenticating the peer certificate.

Field Summary

Fields

Modifier and Type	Field	Description
private javax.net.ssl.X509ExtendedTrustManager	delegateManager
private static java.util.logging.Logger	log
private static int	MINIMUM_REFRESH_PERIOD_IN_MINUTES
private static java.lang.String	NOT_ENOUGH_INFO_MESSAGE
private AdvancedTlsX509TrustManager.SslSocketAndEnginePeerVerifier	socketAndEnginePeerVerifier
private AdvancedTlsX509TrustManager.Verification	verification

Constructor Summary

Constructors

Modifier	Constructor	Description
private	AdvancedTlsX509TrustManager(AdvancedTlsX509TrustManager.Verification verification, AdvancedTlsX509TrustManager.SslSocketAndEnginePeerVerifier socketAndEnginePeerVerifier)

Method Summary

Modifier and Type	Method	Description
void	checkClientTrusted(java.security.cert.X509Certificate[] chain, java.lang.String authType)
void	checkClientTrusted(java.security.cert.X509Certificate[] chain, java.lang.String authType, java.net.Socket socket)
void	checkClientTrusted(java.security.cert.X509Certificate[] chain, java.lang.String authType, javax.net.ssl.SSLEngine engine)
void	checkServerTrusted(java.security.cert.X509Certificate[] chain, java.lang.String authType)
void	checkServerTrusted(java.security.cert.X509Certificate[] chain, java.lang.String authType, java.net.Socket socket)
void	checkServerTrusted(java.security.cert.X509Certificate[] chain, java.lang.String authType, javax.net.ssl.SSLEngine engine)
private void	checkTrusted(java.security.cert.X509Certificate[] chain, java.lang.String authType, javax.net.ssl.SSLEngine sslEngine, java.net.Socket socket, boolean checkingServer)
private static javax.net.ssl.X509ExtendedTrustManager	createDelegateTrustManager(java.security.KeyStore keyStore)
java.security.cert.X509Certificate[]	getAcceptedIssuers()
static AdvancedTlsX509TrustManager.Builder	newBuilder()
private long	readAndUpdate(java.io.File trustCertFile, long oldTime)	Reads the trust certificates specified in the path location, and updates the key store if the modified time has changed since last read.
void	updateTrustCredentials(java.io.File trustCertFile)	Updates the trust certificates from a local file path.
AdvancedTlsX509TrustManager.Closeable	updateTrustCredentials(java.io.File trustCertFile, long period, java.util.concurrent.TimeUnit unit, java.util.concurrent.ScheduledExecutorService executor)	Schedules a ScheduledExecutorService to read trust certificates from a local file path periodically, and updates the cached trust certs if there is an update.
void	updateTrustCredentials(java.security.cert.X509Certificate[] trustCerts)	Updates the current cached trust certificates as well as the key store.
void	updateTrustCredentialsFromFile(java.io.File trustCertFile)	Deprecated. Use updateTrustCredentials(File)
AdvancedTlsX509TrustManager.Closeable	updateTrustCredentialsFromFile(java.io.File trustCertFile, long period, java.util.concurrent.TimeUnit unit, java.util.concurrent.ScheduledExecutorService executor)	Deprecated. Use updateTrustCredentials(File, long ,TimeUnit, ScheduledExecutorService)
void	useSystemDefaultTrustCerts()	Uses the default trust certificates stored on user's local system.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

private static final java.util.logging.Logger log

MINIMUM_REFRESH_PERIOD_IN_MINUTES

private static final int MINIMUM_REFRESH_PERIOD_IN_MINUTES

See Also:

Constant Field Values

NOT_ENOUGH_INFO_MESSAGE

private static final java.lang.String NOT_ENOUGH_INFO_MESSAGE

See Also:

Constant Field Values

verification

private final AdvancedTlsX509TrustManager.Verification verification

socketAndEnginePeerVerifier

private final AdvancedTlsX509TrustManager.SslSocketAndEnginePeerVerifier socketAndEnginePeerVerifier

delegateManager

private volatile javax.net.ssl.X509ExtendedTrustManager delegateManager

Constructor Detail

AdvancedTlsX509TrustManager

private AdvancedTlsX509TrustManager(AdvancedTlsX509TrustManager.Verification verification,
                                    AdvancedTlsX509TrustManager.SslSocketAndEnginePeerVerifier socketAndEnginePeerVerifier)

Method Detail

checkClientTrusted

public void checkClientTrusted(java.security.cert.X509Certificate[] chain,
                               java.lang.String authType)
                        throws java.security.cert.CertificateException

Throws:

java.security.cert.CertificateException

checkClientTrusted

public void checkClientTrusted(java.security.cert.X509Certificate[] chain,
                               java.lang.String authType,
                               java.net.Socket socket)
                        throws java.security.cert.CertificateException

Specified by:

checkClientTrusted in class javax.net.ssl.X509ExtendedTrustManager

Throws:

java.security.cert.CertificateException

checkClientTrusted

public void checkClientTrusted(java.security.cert.X509Certificate[] chain,
                               java.lang.String authType,
                               javax.net.ssl.SSLEngine engine)
                        throws java.security.cert.CertificateException

Specified by:

checkClientTrusted in class javax.net.ssl.X509ExtendedTrustManager

Throws:

java.security.cert.CertificateException

checkServerTrusted

public void checkServerTrusted(java.security.cert.X509Certificate[] chain,
                               java.lang.String authType,
                               javax.net.ssl.SSLEngine engine)
                        throws java.security.cert.CertificateException

Specified by:

checkServerTrusted in class javax.net.ssl.X509ExtendedTrustManager

Throws:

java.security.cert.CertificateException

checkServerTrusted

public void checkServerTrusted(java.security.cert.X509Certificate[] chain,
                               java.lang.String authType)
                        throws java.security.cert.CertificateException

Throws:

java.security.cert.CertificateException

checkServerTrusted

public void checkServerTrusted(java.security.cert.X509Certificate[] chain,
                               java.lang.String authType,
                               java.net.Socket socket)
                        throws java.security.cert.CertificateException

Specified by:

checkServerTrusted in class javax.net.ssl.X509ExtendedTrustManager

Throws:

java.security.cert.CertificateException

getAcceptedIssuers

public java.security.cert.X509Certificate[] getAcceptedIssuers()

useSystemDefaultTrustCerts

public void useSystemDefaultTrustCerts()
                                throws java.security.cert.CertificateException,
                                       java.security.KeyStoreException,
                                       java.security.NoSuchAlgorithmException

Uses the default trust certificates stored on user's local system. After this is used, functions that will provide new credential data(e.g. updateTrustCredentials) should not be called.

Throws:

java.security.cert.CertificateException

java.security.KeyStoreException

java.security.NoSuchAlgorithmException

createDelegateTrustManager

private static javax.net.ssl.X509ExtendedTrustManager createDelegateTrustManager(java.security.KeyStore keyStore)
                                                                          throws java.security.cert.CertificateException,
                                                                                 java.security.KeyStoreException,
                                                                                 java.security.NoSuchAlgorithmException

Throws:

java.security.cert.CertificateException

java.security.KeyStoreException

java.security.NoSuchAlgorithmException

checkTrusted

private void checkTrusted(java.security.cert.X509Certificate[] chain,
                          java.lang.String authType,
                          javax.net.ssl.SSLEngine sslEngine,
                          java.net.Socket socket,
                          boolean checkingServer)
                   throws java.security.cert.CertificateException

Throws:

java.security.cert.CertificateException

updateTrustCredentials

public void updateTrustCredentials(java.security.cert.X509Certificate[] trustCerts)
                            throws java.io.IOException,
                                   java.security.GeneralSecurityException

Updates the current cached trust certificates as well as the key store.

Parameters:

trustCerts - the trust certificates that are going to be used

Throws:

java.io.IOException

java.security.GeneralSecurityException

updateTrustCredentials

public void updateTrustCredentials(java.io.File trustCertFile)
                            throws java.io.IOException,
                                   java.security.GeneralSecurityException

Updates the trust certificates from a local file path.

Parameters:

trustCertFile - the file on disk holding the trust certificates

Throws:

java.io.IOException

java.security.GeneralSecurityException

updateTrustCredentials

public AdvancedTlsX509TrustManager.Closeable updateTrustCredentials(java.io.File trustCertFile,
                                                                    long period,
                                                                    java.util.concurrent.TimeUnit unit,
                                                                    java.util.concurrent.ScheduledExecutorService executor)
                                                             throws java.io.IOException,
                                                                    java.security.GeneralSecurityException

Schedules a ScheduledExecutorService to read trust certificates from a local file path periodically, and updates the cached trust certs if there is an update. You must close the returned Closeable before calling this method again or other update methods (useSystemDefaultTrustCerts(), updateTrustCredentials(X509Certificate[]), updateTrustCredentialsFromFile(File)). Before scheduling the task, the method synchronously reads and updates trust certificates once. If the provided period is less than 1 minute, it is automatically adjusted to 1 minute.

Parameters:

trustCertFile - the file on disk holding the trust certificates

period - the period between successive read-and-update executions

unit - the time unit of the initialDelay and period parameters

executor - the executor service we use to read and update the credentials

Returns:

an object that caller should close when the file refreshes are not needed

Throws:

java.io.IOException

java.security.GeneralSecurityException

updateTrustCredentialsFromFile

@Deprecated
@InlineMe(replacement="this.updateTrustCredentials(trustCertFile, period, unit, executor)")
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8024")
public AdvancedTlsX509TrustManager.Closeable updateTrustCredentialsFromFile(java.io.File trustCertFile,
                                                                            long period,
                                                                            java.util.concurrent.TimeUnit unit,
                                                                            java.util.concurrent.ScheduledExecutorService executor)
                                                                     throws java.io.IOException,
                                                                            java.security.GeneralSecurityException

Deprecated.

Use updateTrustCredentials(File, long ,TimeUnit, ScheduledExecutorService)

Schedules a ScheduledExecutorService to read trust certificates from a local file path periodically, and updates the cached trust certs if there is an update. You must close the returned Closeable before calling this method again or other update methods (useSystemDefaultTrustCerts(), updateTrustCredentials(X509Certificate[]), updateTrustCredentialsFromFile(File)). Before scheduling the task, the method synchronously reads and updates trust certificates once. If the provided period is less than 1 minute, it is automatically adjusted to 1 minute.

Parameters:

trustCertFile - the file on disk holding the trust certificates

period - the period between successive read-and-update executions

unit - the time unit of the initialDelay and period parameters

executor - the executor service we use to read and update the credentials

Returns:

an object that caller should close when the file refreshes are not needed

Throws:

java.io.IOException

java.security.GeneralSecurityException

updateTrustCredentialsFromFile

@Deprecated
@InlineMe(replacement="this.updateTrustCredentials(trustCertFile)")
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8024")
public void updateTrustCredentialsFromFile(java.io.File trustCertFile)
                                    throws java.io.IOException,
                                           java.security.GeneralSecurityException

Deprecated.

Use updateTrustCredentials(File)

Updates the trust certificates from a local file path.

Parameters:

trustCertFile - the file on disk holding the trust certificates

Throws:

java.io.IOException

java.security.GeneralSecurityException

readAndUpdate

private long readAndUpdate(java.io.File trustCertFile,
                           long oldTime)
                    throws java.io.IOException,
                           java.security.GeneralSecurityException

Reads the trust certificates specified in the path location, and updates the key store if the modified time has changed since last read.

Parameters:

trustCertFile - the file on disk holding the trust certificates

oldTime - the time when the trust file is modified during last execution

Returns:

oldTime if failed or the modified time is not changed, otherwise the new modified time

Throws:

java.io.IOException

java.security.GeneralSecurityException

newBuilder

public static AdvancedTlsX509TrustManager.Builder newBuilder()