Package io.grpc.util

Class AdvancedTlsX509KeyManager

java.lang.Object

javax.net.ssl.X509ExtendedKeyManager

io.grpc.util.AdvancedTlsX509KeyManager

All Implemented Interfaces:

KeyManager, X509KeyManager

public final class AdvancedTlsX509KeyManager
extends X509ExtendedKeyManager

AdvancedTlsX509KeyManager is an X509ExtendedKeyManager that allows users to configure advanced TLS features, such as private key and certificate chain reloading.

The alias increments on every credential load (e.g. "key-1", "key-2", ...), so the same alias always maps to the same key material. The previous alias is retained for one rotation to allow in-progress handshakes to complete, ensuring alias-to-key-material consistency across credential reloads.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	AdvancedTlsX509KeyManager.Closeable	Mainly used to avoid throwing IO Exceptions in java.io.Closeable.

Constructor Summary

Constructors

Constructor	Description
AdvancedTlsX509KeyManager()

Method Summary

Modifier and Type	Method	Description
String	chooseClientAlias(String[] keyType, Principal[] issuers, Socket socket)
String	chooseEngineClientAlias(String[] keyType, Principal[] issuers, SSLEngine engine)
String	chooseEngineServerAlias(String keyType, Principal[] issuers, SSLEngine engine)
String	chooseServerAlias(String keyType, Principal[] issuers, Socket socket)
X509Certificate[]	getCertificateChain(String alias)
String[]	getClientAliases(String keyType, Principal[] issuers)
PrivateKey	getPrivateKey(String alias)
String[]	getServerAliases(String keyType, Principal[] issuers)
void	updateIdentityCredentials(File certFile, File keyFile)	Updates certificate chains and the private key from the local file paths.
AdvancedTlsX509KeyManager.Closeable	updateIdentityCredentials(File certFile, File keyFile, long period, TimeUnit unit, ScheduledExecutorService executor)	Schedules a ScheduledExecutorService to read certificate chains and private key from the local file paths periodically, and update the cached identity credentials if they are both updated.
void	updateIdentityCredentials(X509Certificate[] certs, PrivateKey key)	Updates the current cached private key and cert chains.
void	updateIdentityCredentials(PrivateKey key, X509Certificate[] certs)	Deprecated. Use updateIdentityCredentials(X509Certificate[], PrivateKey)
void	updateIdentityCredentialsFromFile(File keyFile, File certFile)	Deprecated. Use updateIdentityCredentials(File, File) instead.
AdvancedTlsX509KeyManager.Closeable	updateIdentityCredentialsFromFile(File keyFile, File certFile, long period, TimeUnit unit, ScheduledExecutorService executor)	Deprecated. Use updateIdentityCredentials(File, File, long, TimeUnit, ScheduledExecutorService) instead.

Methods inherited from class java.lang.Object

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

Constructor Detail

AdvancedTlsX509KeyManager

public AdvancedTlsX509KeyManager()

Method Detail

getPrivateKey

public PrivateKey getPrivateKey(String alias)

getCertificateChain

public X509Certificate[] getCertificateChain(String alias)

getClientAliases

public String[] getClientAliases(String keyType,
                                 Principal[] issuers)

chooseClientAlias

public String chooseClientAlias(String[] keyType,
                                Principal[] issuers,
                                Socket socket)

chooseEngineClientAlias

public String chooseEngineClientAlias(String[] keyType,
                                      Principal[] issuers,
                                      SSLEngine engine)

Overrides:

chooseEngineClientAlias in class X509ExtendedKeyManager

getServerAliases

public String[] getServerAliases(String keyType,
                                 Principal[] issuers)

chooseServerAlias

public String chooseServerAlias(String keyType,
                                Principal[] issuers,
                                Socket socket)

chooseEngineServerAlias

public String chooseEngineServerAlias(String keyType,
                                      Principal[] issuers,
                                      SSLEngine engine)

Overrides:

chooseEngineServerAlias in class X509ExtendedKeyManager

updateIdentityCredentials

@Deprecated
@InlineMe(replacement="this.updateIdentityCredentials(certs, key)")
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8024")
public void updateIdentityCredentials(PrivateKey key,
                                      X509Certificate[] certs)

Deprecated.

Use updateIdentityCredentials(X509Certificate[], PrivateKey)

Updates the current cached private key and cert chains.

Parameters:

key - the private key that is going to be used

certs - the certificate chain that is going to be used

updateIdentityCredentials

public void updateIdentityCredentials(X509Certificate[] certs,
                                      PrivateKey key)

Updates the current cached private key and cert chains.

Parameters:

certs - the certificate chain that is going to be used

key - the private key that is going to be used

updateIdentityCredentials

public AdvancedTlsX509KeyManager.Closeable updateIdentityCredentials(File certFile,
                                                                     File keyFile,
                                                                     long period,
                                                                     TimeUnit unit,
                                                                     ScheduledExecutorService executor)
                                                              throws IOException,
                                                                     GeneralSecurityException

Schedules a ScheduledExecutorService to read certificate chains and private key from the local file paths periodically, and update the cached identity credentials if they are both updated. You must close the returned Closeable before calling this method again or other update methods (updateIdentityCredentials(java.security.PrivateKey, java.security.cert.X509Certificate[]), updateIdentityCredentials(File, File)). Before scheduling the task, the method synchronously executes readAndUpdate once. The minimum refresh period of 1 minute is enforced.

Parameters:

certFile - the file on disk holding the certificate chain

keyFile - the file on disk holding the private key

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

updateIdentityCredentials

public void updateIdentityCredentials(File certFile,
                                      File keyFile)
                               throws IOException,
                                      GeneralSecurityException

Updates certificate chains and the private key from the local file paths.

Parameters:

certFile - the file on disk holding the certificate chain

keyFile - the file on disk holding the private key

Throws:

IOException

GeneralSecurityException

updateIdentityCredentialsFromFile

@Deprecated
@InlineMe(replacement="this.updateIdentityCredentials(certFile, keyFile)")
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8024")
public void updateIdentityCredentialsFromFile(File keyFile,
                                              File certFile)
                                       throws IOException,
                                              GeneralSecurityException

Deprecated.

Use updateIdentityCredentials(File, File) instead.

Updates the private key and certificate chains from the local file paths.

Parameters:

keyFile - the file on disk holding the private key

certFile - the file on disk holding the certificate chain

Throws:

IOException

GeneralSecurityException

updateIdentityCredentialsFromFile

@Deprecated
@InlineMe(replacement="this.updateIdentityCredentials(certFile, keyFile, period, unit, executor)")
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8024")
public AdvancedTlsX509KeyManager.Closeable updateIdentityCredentialsFromFile(File keyFile,
                                                                             File certFile,
                                                                             long period,
                                                                             TimeUnit unit,
                                                                             ScheduledExecutorService executor)
                                                                      throws IOException,
                                                                             GeneralSecurityException

Deprecated.

Use updateIdentityCredentials(File, File, long, TimeUnit, ScheduledExecutorService) instead.

Schedules a ScheduledExecutorService to read private key and certificate chains from the local file paths periodically, and update the cached identity credentials if they are both updated. You must close the returned Closeable before calling this method again or other update methods (updateIdentityCredentials(java.security.PrivateKey, java.security.cert.X509Certificate[]), updateIdentityCredentials(File, File)). Before scheduling the task, the method synchronously executes readAndUpdate once. The minimum refresh period of 1 minute is enforced.

Parameters:

keyFile - the file on disk holding the private key

certFile - the file on disk holding the certificate chain

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