Package io.grpc.util

Class AdvancedTlsX509TrustManager

java.lang.Object

javax.net.ssl.X509ExtendedTrustManager

io.grpc.util.AdvancedTlsX509TrustManager

All Implemented Interfaces:

TrustManager, X509TrustManager

@IgnoreJRERequirement
public final class AdvancedTlsX509TrustManager
extends 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
static interface	AdvancedTlsX509TrustManager.SslSocketAndEnginePeerVerifier
static class	AdvancedTlsX509TrustManager.Verification	The verification mode when authenticating the peer certificate.

Method Summary

Modifier and Type	Method	Description
void	checkClientTrusted(X509Certificate[] chain, String authType)
void	checkClientTrusted(X509Certificate[] chain, String authType, Socket socket)
void	checkClientTrusted(X509Certificate[] chain, String authType, SSLEngine engine)
void	checkServerTrusted(X509Certificate[] chain, String authType)
void	checkServerTrusted(X509Certificate[] chain, String authType, Socket socket)
void	checkServerTrusted(X509Certificate[] chain, String authType, SSLEngine engine)
X509Certificate[]	getAcceptedIssuers()
static AdvancedTlsX509TrustManager.Builder	newBuilder()
void	updateTrustCredentials(File trustCertFile)	Updates the trust certificates from a local file path.
AdvancedTlsX509TrustManager.Closeable	updateTrustCredentials(File trustCertFile, long period, TimeUnit unit, 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(X509Certificate[] trustCerts)	Updates the current cached trust certificates as well as the key store.
void	updateTrustCredentialsFromFile(File trustCertFile)	Deprecated. Use updateTrustCredentials(File)
AdvancedTlsX509TrustManager.Closeable	updateTrustCredentialsFromFile(File trustCertFile, long period, TimeUnit unit, 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

Method Detail

checkClientTrusted

public void checkClientTrusted(X509Certificate[] chain,
                               String authType)
                        throws CertificateException

Throws:

CertificateException

checkClientTrusted

public void checkClientTrusted(X509Certificate[] chain,
                               String authType,
                               Socket socket)
                        throws CertificateException

Specified by:

checkClientTrusted in class X509ExtendedTrustManager

Throws:

CertificateException

checkClientTrusted

public void checkClientTrusted(X509Certificate[] chain,
                               String authType,
                               SSLEngine engine)
                        throws CertificateException

Specified by:

checkClientTrusted in class X509ExtendedTrustManager

Throws:

CertificateException

checkServerTrusted

public void checkServerTrusted(X509Certificate[] chain,
                               String authType,
                               SSLEngine engine)
                        throws CertificateException

Specified by:

checkServerTrusted in class X509ExtendedTrustManager

Throws:

CertificateException

checkServerTrusted

public void checkServerTrusted(X509Certificate[] chain,
                               String authType)
                        throws CertificateException

Throws:

CertificateException

checkServerTrusted

public void checkServerTrusted(X509Certificate[] chain,
                               String authType,
                               Socket socket)
                        throws CertificateException

Specified by:

checkServerTrusted in class X509ExtendedTrustManager

Throws:

CertificateException

getAcceptedIssuers

public X509Certificate[] getAcceptedIssuers()

useSystemDefaultTrustCerts

public void useSystemDefaultTrustCerts()
                                throws CertificateException,
                                       KeyStoreException,
                                       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:

CertificateException

KeyStoreException

NoSuchAlgorithmException

updateTrustCredentials

public void updateTrustCredentials(X509Certificate[] trustCerts)
                            throws IOException,
                                   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:

IOException

GeneralSecurityException

updateTrustCredentials

public void updateTrustCredentials(File trustCertFile)
                            throws IOException,
                                   GeneralSecurityException

Updates the trust certificates from a local file path.

Parameters:

trustCertFile - the file on disk holding the trust certificates

Throws:

IOException

GeneralSecurityException

updateTrustCredentials

public AdvancedTlsX509TrustManager.Closeable updateTrustCredentials(File trustCertFile,
                                                                    long period,
                                                                    TimeUnit unit,
                                                                    ScheduledExecutorService executor)
                                                             throws IOException,
                                                                    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:

IOException

GeneralSecurityException

updateTrustCredentialsFromFile

@Deprecated
@InlineMe(replacement="this.updateTrustCredentials(trustCertFile, period, unit, executor)")
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8024")
public AdvancedTlsX509TrustManager.Closeable updateTrustCredentialsFromFile(File trustCertFile,
                                                                            long period,
                                                                            TimeUnit unit,
                                                                            ScheduledExecutorService executor)
                                                                     throws IOException,
                                                                            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:

IOException

GeneralSecurityException

updateTrustCredentialsFromFile

@Deprecated
@InlineMe(replacement="this.updateTrustCredentials(trustCertFile)")
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8024")
public void updateTrustCredentialsFromFile(File trustCertFile)
                                    throws IOException,
                                           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:

IOException

GeneralSecurityException

newBuilder

public static AdvancedTlsX509TrustManager.Builder newBuilder()