io.grpc

Class TlsServerCredentials

java.lang.Object

io.grpc.ServerCredentials

io.grpc.TlsServerCredentials

public final class TlsServerCredentials
extends ServerCredentials

TLS credentials, providing server identity and encryption. Consumers of this credential must verify they understand the configuration via the incomprehensible() method. Unless overridden by a Feature, server identity is provided via getCertificateChain(), getPrivateKey(), and getPrivateKeyPassword().

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TlsServerCredentials.Builder Builder for TlsServerCredentials.
static class	TlsServerCredentials.ClientAuth The level of authentication the server should expect from the client.
static class	TlsServerCredentials.Feature Features to understand TLS configuration.

Method Summary

Modifier and Type	Method and Description
static ServerCredentials	create(File certChain, File privateKey) Creates an instance using provided certificate chain and private key.
static ServerCredentials	create(InputStream certChain, InputStream privateKey) Creates an instance using provided certificate chain and private key.
byte[]	getCertificateChain() The certificate chain for the server's identity, as a new byte array.
TlsServerCredentials.ClientAuth	getClientAuth() Non-null setting indicating whether the server should expect a client's identity.
List<KeyManager>	getKeyManagers() Returns the key manager list which provides the server's identity.
byte[]	getPrivateKey() The private key for the server's identity, as a new byte array.
String	getPrivateKeyPassword() Returns the password to decrypt the private key, or null if unencrypted.
byte[]	getRootCertificates() Root trust certificates for verifying the client's identity that override the system's defaults.
List<TrustManager>	getTrustManagers() Returns the trust manager list which verifies the client's identity.
Set<TlsServerCredentials.Feature>	incomprehensible(Set<TlsServerCredentials.Feature> understoodFeatures) Returns an empty set if this credential can be adequately understood via the features listed, otherwise returns a hint of features that are lacking to understand the configuration to be used for manual debugging.
static TlsServerCredentials.Builder	newBuilder() Creates a builder for changing default configuration.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static ServerCredentials create(File certChain,
                                       File privateKey)
                                throws IOException

Creates an instance using provided certificate chain and private key. Generally they should be PEM-encoded and the key is an unencrypted PKCS#8 key (file headers have "BEGIN CERTIFICATE" and "BEGIN PRIVATE KEY").

Throws:

IOException

create

public static ServerCredentials create(InputStream certChain,
                                       InputStream privateKey)
                                throws IOException

Creates an instance using provided certificate chain and private key. Generally they should be PEM-encoded and the key is an unencrypted PKCS#8 key (file headers have "BEGIN CERTIFICATE" and "BEGIN PRIVATE KEY").

The streams will not be automatically closed.

Throws:

IOException

getCertificateChain

public byte[] getCertificateChain()

The certificate chain for the server's identity, as a new byte array. Generally should be PEM-encoded. If null, some feature is providing key manager information via a different method.

getPrivateKey

public byte[] getPrivateKey()

The private key for the server's identity, as a new byte array. Generally should be in PKCS#8 format. If encrypted, getPrivateKeyPassword() is the decryption key. If unencrypted, the password will be null. If null, some feature is providing key manager information via a different method.

getPrivateKeyPassword

public String getPrivateKeyPassword()

Returns the password to decrypt the private key, or null if unencrypted.

getKeyManagers

public List<KeyManager> getKeyManagers()

Returns the key manager list which provides the server's identity. Entries are scanned checking for specific types, like X509KeyManager. Only a single entry for a type is used. Entries earlier in the list are higher priority. If null, key manager information is provided via a different method.

getClientAuth

public TlsServerCredentials.ClientAuth getClientAuth()

Non-null setting indicating whether the server should expect a client's identity.

getRootCertificates

public byte[] getRootCertificates()

Root trust certificates for verifying the client's identity that override the system's defaults. Generally PEM-encoded with multiple certificates concatenated.

getTrustManagers

public List<TrustManager> getTrustManagers()

Returns the trust manager list which verifies the client's identity. Entries are scanned checking for specific types, like X509TrustManager. Only a single entry for a type is used. Entries earlier in the list are higher priority. If null, trust manager information is provided via the system's default or a different method.

incomprehensible

public Set<TlsServerCredentials.Feature> incomprehensible(Set<TlsServerCredentials.Feature> understoodFeatures)

Returns an empty set if this credential can be adequately understood via the features listed, otherwise returns a hint of features that are lacking to understand the configuration to be used for manual debugging.

An "understood" feature does not imply the caller is able to fully handle the feature. It simply means the caller understands the feature enough to use the appropriate APIs to read the configuration. The caller may support just a subset of a feature, in which case the caller would need to look at the configuration to determine if only the supported subset is used.

This method may not be as simple as a set difference. There may be multiple features that can independently satisfy a piece of configuration. If the configuration is incomprehensible, all such features would be returned, even though only one may be necessary.

An empty set does not imply that the credentials are fully understood. There may be optional configuration that can be ignored if not understood.

Since Feature is an enum, understoodFeatures should generally be an EnumSet. understoodFeatures will not be modified.

Parameters:

understoodFeatures - the features understood by the caller

Returns:

empty set if the caller can adequately understand the configuration

newBuilder

public static TlsServerCredentials.Builder newBuilder()

Creates a builder for changing default configuration. There is no default key manager, so key material must be specified. The default trust manager uses the system's root certificates. By default no client authentication will occur.