Module org.newsclub.net.unix.ssl

Package org.newsclub.net.unix.ssl

Class SSLContextBuilder

java.lang.Object

org.newsclub.net.unix.ssl.SSLContextBuilder

public final class SSLContextBuilder
extends Object

Helper class to simplify building SSLContext instances.

Author:

Christian Kohlschütter

Method Summary

Modifier and Type	Method	Description
SSLContext	build()	Builds an SSLContext using the current builder state.
SSLContext	buildAndDestroyBuilder()	Builds an SSLContext using the current builder state, and destroys the builder's state, to reduce the chance of information leakage.
void	destroy()	Destroys the state of this builder and all key-/trust-related settings specified.
static SSLContextBuilder	forClient()	Creates an SSLContextBuilder to be used in a client context.
static SSLContextBuilder	forServer()	Creates an SSLContextBuilder to be used in a server context.
static KeyStore	newKeyStorePKCS12()	Returns a new PKCS12 KeyStoreException instance.
SSLContextBuilder	withDefaultSSLParameters(Consumer<SSLParameters> consumer)	Configures this builder to use the given consumer to configure the default SSL parameters.
SSLContextBuilder	withDefaultSSLParameters(Function<SSLParameters,SSLParameters> function)	Configures this builder to use the given function to configure the default SSL parameters.
SSLContextBuilder	withKeyManagers(SSLFunction<KeyManagerFactory,KeyManager[]> s)	Configures this builder to use the given supplier for {link KeyManager}[].
SSLContextBuilder	withKeyStore(File path, SSLSupplier<char[]> password)	Configures this builder to use the given keystore, identified by path and password.
SSLContextBuilder	withKeyStore(URL url, SSLSupplier<char[]> password)	Configures this builder to use the given keystore, identified by URL and password.
SSLContextBuilder	withKeyStoreSupplier(SSLSupplier<KeyStore> supplier)	Configures this builder to use the given supplier to provide KeyStore instances.
SSLContextBuilder	withProtocol(String p)	Configures this builder to use the given protocol.
SSLContextBuilder	withProvider(String id)	Configures this builder to use the given provider, identified by ID, null being the default.
SSLContextBuilder	withProvider(Provider p)	Configures this builder to use the given provider, null being the default.
SSLContextBuilder	withSecureRandom(SecureRandom s)	Configures this builder to use the given protocol.
SSLContextBuilder	withSocketFactory(SocketFactory sf)	Configures this builder to use the given SocketFactory to create the underlying insecure sockets.
SSLContextBuilder	withTrustManagers(SSLFunction<TrustManagerFactory,TrustManager[]> s)	Configures this builder to use the given supplier for TrustManager[].
SSLContextBuilder	withTrustStore(File path, SSLSupplier<char[]> password)	Configures this builder to use the given truststore, identified by path and password.
SSLContextBuilder	withTrustStore(URL url, SSLSupplier<char[]> password)	Configures this builder to use the given truststore, identified by path and password.
static IOException	wrapIOExceptionIfJDKBug(IOException e)	For a given IOException thrown from within SSLContextBuilder, check if it is due to a known JDK bug, and if so, wrap that exception in a KnownJavaBugIOException with a proper explanation.

Methods inherited from class java.lang.Object

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

Method Details

forServer

public static SSLContextBuilder forServer()

Creates an SSLContextBuilder to be used in a server context.

Returns:

The builder instance.

forClient

public static SSLContextBuilder forClient()

Creates an SSLContextBuilder to be used in a client context.

Returns:

The builder instance.

withSocketFactory

public SSLContextBuilder withSocketFactory(SocketFactory sf)

Configures this builder to use the given SocketFactory to create the underlying insecure sockets.

Parameters:

sf - The SocketFactory.

Returns:

This builder.

withProtocol

public SSLContextBuilder withProtocol(String p)

Configures this builder to use the given protocol. Note that "TLS" is the default.

Parameters:

p - The protocol to use, e.g. TLSv1.2.

Returns:

This builder.

withProvider

public SSLContextBuilder withProvider(Provider p)

Configures this builder to use the given provider, null being the default.

Parameters:

p - The provider to use, e.g. BouncyCastleJsseProvider, or null for system default.

Returns:

This builder.

withProvider

public SSLContextBuilder withProvider(String id)

Configures this builder to use the given provider, identified by ID, null being the default.

In addition to the standard JSSE IDs, you can specify one or more Provider classnames as a comma-separated list. These providers will be added via Security.addProvider(Provider). The first entry is then attempted to be resolved using Provider.getName(), with any optionally remaining Providers simply being added to the list of available providers, in case they're actually required by the first one. It is expected that the classes have a public no-arg constructor.

This is the case, for example, with BouncyCastle. Specify org.bouncycastle.jsse.provider.BouncyCastleJsseProvider,org.bouncycastle.jce.provider.BouncyCastleProvider to enable TLS-secured communication with PKCS12 keys, for example.

Parameters:

id - The provider to use, e.g. BCJSSE, or null/"" for system default.

Returns:

This builder.

withKeyManagers

public SSLContextBuilder withKeyManagers(SSLFunction<KeyManagerFactory,KeyManager[]> s)

Configures this builder to use the given supplier for {link KeyManager}[]. Note that setting any value other than null means that the parameters specified with withKeyStore(File, SSLSupplier), etc. are ignored.

Parameters:

s - The supplier to use, or null to use the built-in default.

Returns:

This builder.

Throws:

IllegalStateException - if withKeyStore(File, SSLSupplier), etc., was already called.

withTrustManagers

public SSLContextBuilder withTrustManagers(SSLFunction<TrustManagerFactory,TrustManager[]> s)

Configures this builder to use the given supplier for TrustManager[]. Note that setting any value other than null means that the parameters specified with withTrustStore(File, SSLSupplier), etc. are ignored.

Parameters:

s - The supplier to use, or null to use the built-in default.

Returns:

This builder.

withSecureRandom

public SSLContextBuilder withSecureRandom(SecureRandom s)

Configures this builder to use the given protocol. Note that "null" is the default, which means that it's up the SSL implementation what SecureRandom to use.

Parameters:

s - The instance to use, e.g. null.

Returns:

This builder.

withKeyStoreSupplier

public SSLContextBuilder withKeyStoreSupplier(SSLSupplier<KeyStore> supplier)

Configures this builder to use the given supplier to provide KeyStore instances. If null is specified, the default supplier is used, which is configured for PKCS12-type keystores. In that case, on Android, it is expected that the BouncyCastle SSL provider (org.bouncycastle.jce.provider.BouncyCastleProvider) is on the classpath.

Parameters:

supplier - The supplier, or null for default.

Returns:

This builder.

withKeyStore

public SSLContextBuilder withKeyStore(File path,
 SSLSupplier<char[]> password)
                               throws FileNotFoundException,
MalformedURLException

Configures this builder to use the given keystore, identified by path and password.

Parameters:

path - The path to the keystore.

password - The supplier that returns the password to unlock the keystore; the password will be overwritten with blanks immediately after use.

Returns:

This builder.

Throws:

FileNotFoundException - on error.

MalformedURLException - on error.

IllegalStateException - if withKeyManagers(SSLFunction) was already called.

See Also:

• withKeyManagers(SSLFunction)

withKeyStore

public SSLContextBuilder withKeyStore(URL url,
 SSLSupplier<char[]> password)
                               throws FileNotFoundException

Configures this builder to use the given keystore, identified by URL and password.

Parameters:

url - The URL specifying the location of the keystore

password - The supplier that returns the password to unlock the keystore; the password will be overwritten with blanks immediately after use.

Returns:

This builder.

Throws:

FileNotFoundException - on error.

See Also:

• withKeyManagers(SSLFunction)

withTrustStore

public SSLContextBuilder withTrustStore(File path,
 SSLSupplier<char[]> password)
                                 throws FileNotFoundException,
MalformedURLException

Configures this builder to use the given truststore, identified by path and password.

Parameters:

path - The path to the truststore.

password - The supplier that returns the password to unlock the keystore; the password will be overwritten with blanks immediately after use.

Returns:

This builder.

Throws:

FileNotFoundException - on error.

MalformedURLException - on error.

See Also:

• withTrustManagers(SSLFunction)

withTrustStore

public SSLContextBuilder withTrustStore(URL url,
 SSLSupplier<char[]> password)
                                 throws FileNotFoundException

Configures this builder to use the given truststore, identified by path and password.

Parameters:

url - The URL specifying the location of the truststore.

password - The supplier that returns the password to unlock the keystore; the password will be overwritten with blanks immediately after use.

Returns:

This builder.

Throws:

FileNotFoundException - on error.

See Also:

• withTrustManagers(SSLFunction)

withDefaultSSLParameters

public SSLContextBuilder withDefaultSSLParameters(Function<SSLParameters,SSLParameters> function)

Configures this builder to use the given function to configure the default SSL parameters. The function is called with the context's default SSL parameters instance. The function may modify and return the given instance, or return a completely different instance.

Parameters:

function - The function to configure SSL parameters.

Returns:

This builder.

withDefaultSSLParameters

public SSLContextBuilder withDefaultSSLParameters(Consumer<SSLParameters> consumer)

Configures this builder to use the given consumer to configure the default SSL parameters. The consumer is called with the context's default SSL parameters instance. The consumer may modify or just inspect the given instance.

Parameters:

consumer - The function to configure SSL parameters.

Returns:

This builder.

wrapIOExceptionIfJDKBug

public static IOException wrapIOExceptionIfJDKBug(IOException e)

For a given IOException thrown from within SSLContextBuilder, check if it is due to a known JDK bug, and if so, wrap that exception in a KnownJavaBugIOException with a proper explanation.

Parameters:

e - The exception to check/wrap.

Returns:

The exception, or a KnownJavaBugIOException.

build

public SSLContext build()
                 throws GeneralSecurityException,
IOException

Builds an SSLContext using the current builder state.

IMPORTANT: Use buildAndDestroyBuilder() to ensure sensitive information, such as passwords, are properly destroyed/removed from memory.

Returns:

The new SSLContext instance.

Throws:

GeneralSecurityException - on error.

IOException - on error.

See Also:

• buildAndDestroyBuilder()

buildAndDestroyBuilder

public SSLContext buildAndDestroyBuilder()
                                  throws GeneralSecurityException,
IOException,
DestroyFailedException

Builds an SSLContext using the current builder state, and destroys the builder's state, to reduce the chance of information leakage.

Returns:

The new SSLContext instance.

Throws:

GeneralSecurityException - on error.

IOException - on error.

DestroyFailedException - on error.

See Also:

• destroy()

destroy

public void destroy()
             throws DestroyFailedException

Destroys the state of this builder and all key-/trust-related settings specified.

Throws:

DestroyFailedException - on error (thrown at the end, to increase level of destruction).

newKeyStorePKCS12

public static KeyStore newKeyStorePKCS12()
                                  throws KeyStoreException

Returns a new PKCS12 KeyStoreException instance.

Returns:

The keystore instance.

Throws:

KeyStoreException - on error.