org.snf4j.core.session.ssl

Class SSLContextBuilder

java.lang.Object

org.snf4j.core.session.ssl.SSLContextBuilder

All Implemented Interfaces:

Destroyable

public class SSLContextBuilder
extends Object
implements Destroyable

A builder for the SSLContext.

Author:

SNF4J.ORG

Method Summary

Modifier and Type	Method and Description
SSLContext	build() Builds a new SSLContext instance based on the current configuration settings.
SSLContextBuilder	cipherFilter(CipherFilter filter) Configures a filter for cipher suites to enable, or null to use the default filter.
SSLContextBuilder	ciphers(String... ciphers) Configures cipher suites to enable, or null to enable the recommended cipher suites.
SSLContextBuilder	clientAuth(ClientAuth clientAuth) Configures the client authentication mode for a server-side SSLEngine.
void	destroy() Destroys sensitive information associated with this builder (i.e.
SSLContextBuilder	enableRetransmissions(boolean enable) Configures if DTLS handshake retransmissions should be enabled.
SSLEngineBuilder	engineBuilder() Creates a new SSLEngine builder pre-configured with the current configuration settings.
static SSLContextBuilder	forClient() Creates a builder for a client-side SSLContext.
static SSLContextBuilder	forServer(File keyFile, char[] password, File keyCertsFile) Creates a builder for a server-side SSLContext.
static SSLContextBuilder	forServer(File keyFile, File keyCertsFile) Creates a builder for a server-side SSLContext.
static SSLContextBuilder	forServer(InputStream keyIn, char[] password, InputStream keyCertsIn) Creates a builder for a server-side SSLContext.
static SSLContextBuilder	forServer(InputStream keyIn, InputStream keyCertsIn) Creates a builder for a server-side SSLContext.
static SSLContextBuilder	forServer(KeyManagerFactory keyFactory) Creates a builder for a server-side SSLContext.
static SSLContextBuilder	forServer(PrivateKey key, char[] password, X509Certificate... keyCerts) Creates a builder for a server-side SSLContext.
static SSLContextBuilder	forServer(PrivateKey key, X509Certificate... keyCerts) Creates a builder for a server-side SSLContext.
boolean	isDestroyed() Tells if sensitive information associated with this builder is destroyed
boolean	isForClient() Tells if the builder if for a client-side SSLContext.
boolean	isForServer() Tells if the builder if for a server-side SSLContext.
SSLContextBuilder	keyManager(File keyFile, char[] password, File keyCertsFile) Configures a private key with certificate chain for host identification.
SSLContextBuilder	keyManager(File keyFile, File keyCertsFile) Configures a private key with certificate chain for host identification.
SSLContextBuilder	keyManager(InputStream keyIn, char[] password, InputStream keyCertsIn) Configures a private key with certificate chain for host identification.
SSLContextBuilder	keyManager(InputStream keyIn, InputStream keyCertsIn) Configures a private key with certificate chain for host identification.
SSLContextBuilder	keyManager(KeyManagerFactory keyFactory) Configures a private key with certificate chain for host identification.
SSLContextBuilder	keyManager(PrivateKey key, char[] password, X509Certificate... keyCerts) Configures a private key with certificate chain for host identification.
SSLContextBuilder	keyManager(PrivateKey key, X509Certificate... keyCerts) Configures a private key with certificate chain for host identification.
SSLContextBuilder	maximumPacketSize(int maxSize) Configures the maximum expected network packet size.
SSLContextBuilder	protocol(String protocol) Configures the protocol name of the SSLContext to be created by this builder.
SSLContextBuilder	protocolFilter(ProtocolFilter filter) Configures a filter for protocol versions to enable, or null to use the default filter.
SSLContextBuilder	protocols(String... protocols) Configures protocol versions to enable, or null to enable the recommended protocol versions.
SSLContextBuilder	provider(Provider provider) Configures the provide of the SSLContext to be created by this builder.
SSLContextBuilder	providerName(String provider) Configures the provider name of the SSLContext to be created by this builder.
SSLContextBuilder	secureRandom(SecureRandom random) Configures a secure source of randomness.
SSLContextBuilder	sessionCacheSize(int size) Configures the size of the cache used for storing the SSL session objects.
SSLContextBuilder	sessionTimeout(int timeout) Configures the timeout limit for the cached SSL session objects.
SSLContextBuilder	trustManager(File trustCertsFile) Configures trusted certificates for remote hosts verification.
SSLContextBuilder	trustManager(InputStream trustCertsIn) Configures trusted certificates for remote hosts verification.
SSLContextBuilder	trustManager(TrustManagerFactory trustFactory) Configures trusted certificates for remote hosts verification.
SSLContextBuilder	trustManager(X509Certificate... trustCerts) Configures trusted certificates for remote hosts verification.
SSLContextBuilder	useCiphersOrder(boolean useOrder) Configures if the local cipher suites preferences should be honored during SSL/TLS/DTLS handshaking

Methods inherited from class java.lang.Object

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

Method Detail

forClient

public static SSLContextBuilder forClient()

Creates a builder for a client-side SSLContext.

Returns:

a builder for a client-side SSLContext

forServer

public static SSLContextBuilder forServer(File keyFile,
                                          File keyCertsFile)
                                   throws IOException,
                                          KeyException,
                                          CertificateException

Creates a builder for a server-side SSLContext.

Parameters:

keyFile - a file for a PKCS#8 private key in the PEM encoding

keyCertsFile - a file for an X.509 certificate chain in the PEM encoding

Returns:

a builder for a server-side SSLContext

Throws:

IOException - if a failure occurred while reading the files

KeyException - if a failure occurred while creating the key

CertificateException - if a failure occurred while creating the certificates

forServer

public static SSLContextBuilder forServer(File keyFile,
                                          char[] password,
                                          File keyCertsFile)
                                   throws IOException,
                                          KeyException,
                                          CertificateException

Creates a builder for a server-side SSLContext.

Parameters:

keyFile - a file for a PKCS#8 private key in the PEM encoding

password - the password protecting the private key, or null if the key is not password-protected

keyCertsFile - a file for an X.509 certificate chain in the PEM encoding

Returns:

a builder for a server-side SSLContext

Throws:

IOException - if a failure occurred while reading the files

KeyException - if a failure occurred while creating the key

CertificateException - if a failure occurred while creating the certificates

forServer

public static SSLContextBuilder forServer(InputStream keyIn,
                                          InputStream keyCertsIn)
                                   throws IOException,
                                          KeyException,
                                          CertificateException

Creates a builder for a server-side SSLContext.

Parameters:

keyIn - an input stream for a PKCS#8 private key in the PEM encoding

keyCertsIn - an input stream for an X.509 certificate chain in the PEM encoding

Returns:

a builder for a server-side SSLContext

Throws:

IOException - if a failure occurred while reading from the input streams

KeyException - if a failure occurred while creating the key

CertificateException - if a failure occurred while creating the certificates

forServer

public static SSLContextBuilder forServer(InputStream keyIn,
                                          char[] password,
                                          InputStream keyCertsIn)
                                   throws IOException,
                                          KeyException,
                                          CertificateException

Creates a builder for a server-side SSLContext.

Parameters:

keyIn - an input stream for a PKCS#8 private key in the PEM encoding

password - the password protecting the private key, or null if the key is not password-protected

keyCertsIn - an input stream for an X.509 certificate chain in the PEM encoding

Returns:

a builder for a server-side SSLContext

Throws:

IOException - if a failure occurred while reading from the input streams

KeyException - if a failure occurred while creating the key

CertificateException - if a failure occurred while creating the certificates

forServer

public static SSLContextBuilder forServer(PrivateKey key,
                                          X509Certificate... keyCerts)

Creates a builder for a server-side SSLContext.

Parameters:

key - a PKCS#8 private key

keyCerts - an X.509 certificate chain

Returns:

a builder for a server-side SSLContext

forServer

public static SSLContextBuilder forServer(PrivateKey key,
                                          char[] password,
                                          X509Certificate... keyCerts)

Creates a builder for a server-side SSLContext.

Parameters:

key - a PKCS#8 private key

password - the password protecting the private key, or null if the key is not password-protected

keyCerts - an X.509 certificate chain

Returns:

a builder for a server-side SSLContext

forServer

public static SSLContextBuilder forServer(KeyManagerFactory keyFactory)

Creates a builder for a server-side SSLContext.

Parameters:

keyFactory - a factory for a private key

Returns:

a builder for a server-side SSLContext

isForServer

public boolean isForServer()

Tells if the builder if for a server-side SSLContext.

Returns:

true if the builder if for a server-side SSLContext

isForClient

public boolean isForClient()

Tells if the builder if for a client-side SSLContext.

Returns:

true if the builder if for a client-side SSLContext

protocol

public SSLContextBuilder protocol(String protocol)

Configures the protocol name of the SSLContext to be created by this builder.

Parameters:

protocol - the protocol name

Returns:

this builder

protocols

public SSLContextBuilder protocols(String... protocols)

Configures protocol versions to enable, or null to enable the recommended protocol versions.

This configuration is used to pre-configure the SSLEngineBuilder returned by the engineBuilder() method.

Parameters:

protocols - the protocol versions

Returns:

this builder

protocolFilter

public SSLContextBuilder protocolFilter(ProtocolFilter filter)

Configures a filter for protocol versions to enable, or null to use the default filter.

This configuration is used to pre-configure the SSLEngineBuilder returned by the engineBuilder() method.

Parameters:

filter - the protocol filter

Returns:

this builder

ciphers

public SSLContextBuilder ciphers(String... ciphers)

Configures cipher suites to enable, or null to enable the recommended cipher suites.

This configuration is used to pre-configure the SSLEngineBuilder returned by the engineBuilder() method.

Parameters:

ciphers - the cipher suites

Returns:

this builder

cipherFilter

public SSLContextBuilder cipherFilter(CipherFilter filter)

Configures a filter for cipher suites to enable, or null to use the default filter.

This configuration is used to pre-configure the SSLEngineBuilder returned by the engineBuilder() method.

Parameters:

filter - the cipher filter

Returns:

this builder

enableRetransmissions

public SSLContextBuilder enableRetransmissions(boolean enable)

Configures if DTLS handshake retransmissions should be enabled.

This configuration is used to pre-configure the SSLEngineBuilder returned by the engineBuilder() method.

NOTE: It requires Java 9 or newer.

Parameters:

enable - true to enable DTLS handshake retransmissions.

Returns:

this builder

maximumPacketSize

public SSLContextBuilder maximumPacketSize(int maxSize)

Configures the maximum expected network packet size.

This configuration is used to pre-configure the SSLEngineBuilder returned by the engineBuilder() method.

NOTE: It requires Java 9 or newer.

Parameters:

maxSize - the maximum expected network packet size in bytes, or 0 to use the default value that is specified by the underlying implementation.

Returns:

this builder

useCiphersOrder

public SSLContextBuilder useCiphersOrder(boolean useOrder)

Configures if the local cipher suites preferences should be honored during SSL/TLS/DTLS handshaking

This configuration is used to pre-configure the SSLEngineBuilder returned by the engineBuilder() method.

Parameters:

useOrder - true to honor the local cipher suites preferences

Returns:

this builder

clientAuth

public SSLContextBuilder clientAuth(ClientAuth clientAuth)

Configures the client authentication mode for a server-side SSLEngine.

This configuration is used to pre-configure the SSLEngineBuilder returned by the engineBuilder() method.

Parameters:

clientAuth - the client authentication mode.

Returns:

this builder

provider

public SSLContextBuilder provider(Provider provider)

Configures the provide of the SSLContext to be created by this builder.

Parameters:

provider - the provider

Returns:

this builder

providerName

public SSLContextBuilder providerName(String provider)

Configures the provider name of the SSLContext to be created by this builder.

Parameters:

provider - the provider name

Returns:

this builder

sessionTimeout

public SSLContextBuilder sessionTimeout(int timeout)

Configures the timeout limit for the cached SSL session objects.

Parameters:

timeout - the timeout limit in seconds, or 0 to set no limit.

Returns:

this builder

sessionCacheSize

public SSLContextBuilder sessionCacheSize(int size)

Configures the size of the cache used for storing the SSL session objects.

Parameters:

size - the cache size limit, or 0 to set no limit.

Returns:

this builder

trustManager

public SSLContextBuilder trustManager(File trustCertsFile)
                               throws IOException,
                                      CertificateException

Configures trusted certificates for remote hosts verification.

Parameters:

trustCertsFile - a file for X.509 certificates in the PEM encoding

Returns:

this builder

Throws:

IOException - if a failure occurred while reading the files

CertificateException - if a failure occurred while creating the

trustManager

public SSLContextBuilder trustManager(InputStream trustCertsIn)
                               throws IOException,
                                      CertificateException

Configures trusted certificates for remote hosts verification.

Parameters:

trustCertsIn - an input stream for X.509 certificates in the PEM encoding

Returns:

this builder

Throws:

IOException - if a failure occurred while reading the files

CertificateException - if a failure occurred while creating the

trustManager

public SSLContextBuilder trustManager(X509Certificate... trustCerts)

Configures trusted certificates for remote hosts verification.

Parameters:

trustCerts - X.509 certificates

Returns:

this builder

trustManager

public SSLContextBuilder trustManager(TrustManagerFactory trustFactory)

Configures trusted certificates for remote hosts verification.

Parameters:

trustFactory - a factory for trusted certificates

Returns:

this builder

keyManager

public SSLContextBuilder keyManager(File keyFile,
                                    File keyCertsFile)
                             throws IOException,
                                    KeyException,
                                    CertificateException

Configures a private key with certificate chain for host identification.

Parameters:

keyFile - a file for a PKCS#8 private key in the PEM encoding

keyCertsFile - a file for an X.509 certificate chain in the PEM encoding

Returns:

this builder

Throws:

IOException - if a failure occurred while reading the files

KeyException - if a failure occurred while creating the key

CertificateException - if a failure occurred while creating the certificates

keyManager

public SSLContextBuilder keyManager(File keyFile,
                                    char[] password,
                                    File keyCertsFile)
                             throws IOException,
                                    KeyException,
                                    CertificateException

Configures a private key with certificate chain for host identification.

Parameters:

keyFile - a file for a PKCS#8 private key in the PEM encoding

password - the password protecting the private key, or null if the key is not password-protected

keyCertsFile - a file for an X.509 certificate chain in the PEM encoding

Returns:

this builder

Throws:

IOException - if a failure occurred while reading the files

KeyException - if a failure occurred while creating the key

CertificateException - if a failure occurred while creating the certificates

keyManager

public SSLContextBuilder keyManager(InputStream keyIn,
                                    InputStream keyCertsIn)
                             throws IOException,
                                    KeyException,
                                    CertificateException

Configures a private key with certificate chain for host identification.

Parameters:

keyIn - an input stream for a PKCS#8 private key in the PEM encoding

keyCertsIn - an input stream for an X.509 certificate chain in the PEM encoding

Returns:

this builder

Throws:

IOException - if a failure occurred while reading from the input streams

KeyException - if a failure occurred while creating the key

CertificateException - if a failure occurred while creating the certificates

keyManager

public SSLContextBuilder keyManager(InputStream keyIn,
                                    char[] password,
                                    InputStream keyCertsIn)
                             throws IOException,
                                    KeyException,
                                    CertificateException

Configures a private key with certificate chain for host identification.

Parameters:

keyIn - an input stream for a PKCS#8 private key in the PEM encoding

password - the password protecting the private key, or null if the key is not password-protected

keyCertsIn - an input stream for an X.509 certificate chain in the PEM encoding

Returns:

this builder

Throws:

IOException - if a failure occurred while reading from the input streams

KeyException - if a failure occurred while creating the key

CertificateException - if a failure occurred while creating the certificates

keyManager

public SSLContextBuilder keyManager(PrivateKey key,
                                    X509Certificate... keyCerts)

Configures a private key with certificate chain for host identification.

Parameters:

key - a PKCS#8 private key

keyCerts - an X.509 certificate chain

Returns:

this builder

keyManager

public SSLContextBuilder keyManager(PrivateKey key,
                                    char[] password,
                                    X509Certificate... keyCerts)

Configures a private key with certificate chain for host identification.

Parameters:

key - a PKCS#8 private key

password - the password protecting the private key, or null if the key is not password-protected

keyCerts - an X.509 certificate chain

Returns:

this builder

keyManager

public SSLContextBuilder keyManager(KeyManagerFactory keyFactory)

Configures a private key with certificate chain for host identification.

Parameters:

keyFactory - a factory for a private key

Returns:

this builder

secureRandom

public SSLContextBuilder secureRandom(SecureRandom random)

Configures a secure source of randomness.

Parameters:

random - the source of randomness, or null to use the default source.

Returns:

this builder

engineBuilder

public SSLEngineBuilder engineBuilder()
                               throws SSLContextCreateException

Creates a new SSLEngine builder pre-configured with the current configuration settings. The returned builder is constructed with a new SSLContext created by calling the build() method.

Returns:

the new SSLEngine builder

Throws:

SSLContextCreateException - if a failure occurred while building the SSLContext instance used to construct the new SSLEngine builder

build

public SSLContext build()
                 throws SSLContextCreateException

Builds a new SSLContext instance based on the current configuration settings.

Returns:

the new SSLContext instance.

Throws:

SSLContextCreateException - if a failure occurred while building the SSLContext instance

destroy

public void destroy()
             throws DestroyFailedException

Destroys sensitive information associated with this builder (i.e. password and private key).

Specified by:

destroy in interface Destroyable

Throws:

DestroyFailedException - if the destroy operation failed

isDestroyed

public boolean isDestroyed()

Tells if sensitive information associated with this builder is destroyed

Specified by:

isDestroyed in interface Destroyable

Returns:

true if the sensitive information is destroyed