io.grpc

Class TlsChannelCredentials

java.lang.Object

io.grpc.ChannelCredentials

io.grpc.TlsChannelCredentials

public final class TlsChannelCredentials
extends ChannelCredentials

TLS credentials, providing server authentication and encryption. Consumers of this credential must verify they understand the configuration via the incomprehensible() method. Unless overridden by a Feature, server verification should use customary default root certificates.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TlsChannelCredentials.Builder Builder for TlsChannelCredentials.
static class	TlsChannelCredentials.Feature Features to understand TLS configuration.

Method Summary

Modifier and Type	Method and Description
static ChannelCredentials	create() Use TLS with its defaults.
byte[]	getCertificateChain() The certificate chain for the client's identity, as a new byte array.
List<KeyManager>	getKeyManagers() Returns the key manager list which provides the client's identity.
byte[]	getPrivateKey() The private key for the client'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 server's identity that override the system's defaults.
List<TrustManager>	getTrustManagers() Returns the trust manager list which verifies the server's identity.
Set<TlsChannelCredentials.Feature>	incomprehensible(Set<TlsChannelCredentials.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 TlsChannelCredentials.Builder	newBuilder() Creates a builder for changing default configuration.
ChannelCredentials	withoutBearerTokens() Returns the ChannelCredentials stripped of its CallCredentials.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static ChannelCredentials create()

Use TLS with its defaults.

getCertificateChain

public byte[] getCertificateChain()

The certificate chain for the client'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 or no client identity is available.

getPrivateKey

public byte[] getPrivateKey()

The private key for the client'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 or no client identity is available.

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 client'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 or no client identity is available.

getRootCertificates

public byte[] getRootCertificates()

Root trust certificates for verifying the server'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 server'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<TlsChannelCredentials.Feature> incomprehensible(Set<TlsChannelCredentials.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

withoutBearerTokens

public ChannelCredentials withoutBearerTokens()

Description copied from class: ChannelCredentials

Returns the ChannelCredentials stripped of its CallCredentials. In the future, this may strip only some of the CallCredentials, preserving call credentials that are safe from replay attacks (e.g., if the token is bound to the channel's certificate).

Specified by:

withoutBearerTokens in class ChannelCredentials

newBuilder

public static TlsChannelCredentials.Builder newBuilder()

Creates a builder for changing default configuration.