org.mule.api.security.tls
Class TlsConfiguration

java.lang.Object
  org.mule.api.security.tls.TlsConfiguration

All Implemented Interfaces:

TlsDirectKeyStore, TlsDirectTrustStore, TlsIndirectKeyStore, TlsIndirectTrustStore, TlsProtocolHandler

public final class TlsConfiguration
extends Object
implements TlsDirectTrustStore, TlsDirectKeyStore, TlsIndirectKeyStore, TlsProtocolHandler

Support for configuring TLS/SSL connections.

Introduction

This class was introduced to centralise the work of TLS/SSL configuration. It is intended to be backwards compatible with earlier code (as much as possible) and so is perhaps more complex than would be necessary if starting from zero - the main source of confusion is the distinction between direct and indirect creation of sockets and stores.

Configuration

The documentation in this class is intended more for programmers than end uses. If you are configuring a connector the interfaces TlsIndirectTrustStore, TlsDirectTrustStore, TlsDirectKeyStore and TlsIndirectKeyStore should provide guidance to individual properties. In addition you should check the documentation for the specific protocol / connector used and may also need to read the discussion on direct and indirect socket and store creation below (or, more simply, just use whichever key store interface your connector implements!).

Programming

This class is intended to be used as a delegate as we typically want to add security to an already existing connector (so we inherit from that connector, implement the appropriate interfaces from TlsIndirectTrustStore, TlsDirectTrustStore, TlsDirectKeyStore and TlsIndirectKeyStore, and then forward calls to the interfaces to an instance of this class).

For setting System properties (and reading them) use TlsPropertiesMapper. This can take a "namespace" which can then be used by TlsPropertiesSocketFactory to construct an appropriate socket factory. This approach (storing to properties and then retrieving that information later in a socket factory) lets us pass TLS/SSL configuration into libraries that are configured by specifying on the socket factory class.

Direct and Indirect Socket and Store Creation

For the SSL transport, which historically defined parameters for many different secure transports, the configuration interfaces worked as follows:

TlsDirectTrustStore

Used to generate trust store directly and indirectly for all TLS/SSL conections via System properties

TlsDirectKeyStore

Used to generate key store directly

TlsIndirectKeyStore

Used to generate key store indirectly for all TLS/SSL conections via System properties

Historically, many other transports relied on the indirect configurations defined above. So they implemented TlsIndirectTrustStore (a superclass of TlsDirectTrustStore) and relied on TlsIndirectKeyStore from the SSL configuration. For continuity these interfaces continue to be used, even though the configurations are now typically (see individual connector/protocol documentation) specific to a protocol or connector. Note - these interfaces are new, but the original code had those methods, used as described. The new interfaces only make things explicit.

Note for programmers One way to understand the above is to see that many protocols are handled by libraries that are configured by providing either properties or a socket factory. In both cases (the latter via TlsPropertiesSocketFactory) we continue to use properties and the "indirect" interface. Note also that the mapping in TlsPropertiesMapper correctly handles the asymmetry, so an initial call to TlsConfiguration uses the keystore defined via TlsDirectKeyStore, but when a TlsConfiguration is retrieved from System proerties using TlsPropertiesMapper.readFromProperties(TlsConfiguration,java.util.Properties) the "indirect" properties are supplied as "direct" values, meaning that the "indirect" socket factory can be retrieved from getKeyManagerFactory(). It just works.

Field Summary

static String	DEFAULT_KEYSTORE
static String	DEFAULT_KEYSTORE_TYPE
static String	DEFAULT_SSL_TYPE
static String	JSSE_NAMESPACE

Constructor Summary

TlsConfiguration(String keyStore)
Support for TLS connections with a given initial value for the key store

Method Summary

String	getClientKeyStore()
String	getClientKeyStorePassword()
String	getClientKeyStoreType()
String	getKeyManagerAlgorithm()
KeyManagerFactory	getKeyManagerFactory()
String	getKeyPassword()
String	getKeyStore()
String	getKeyStorePassword()
String	getKeyStoreType()
String	getProtocolHandler()
Provider	getProvider()
SecurityProviderFactory	getSecurityProviderFactory()
SSLServerSocketFactory	getServerSocketFactory()
SSLSocketFactory	getSocketFactory()
SSLContext	getSslContext()
String	getSslType()
String	getTrustManagerAlgorithm()
TrustManagerFactory	getTrustManagerFactory()
String	getTrustStore()
String	getTrustStorePassword()
String	getTrustStoreType()
void	initialise(boolean anon, String namespace)
boolean	isExplicitTrustStoreOnly() If the trust store is undefined and the trust store generated via System properties then the key store certificates defined via TODO can be used as a source of trust information.
boolean	isRequireClientAuthentication() If a server socket is constructed directly (see TlsConfiguration) then this flag will control whether client authenticatin is required.
void	setClientKeyStore(String name)
void	setClientKeyStorePassword(String clientKeyStorePassword)
void	setClientKeyStoreType(String clientKeyStoreType)
void	setExplicitTrustStoreOnly(boolean explicitTrustStoreOnly) If the trust store is undefined and the trust store generated via System properties then the key store certificates defined via TODO can be used as a source of trust information.
void	setKeyManagerAlgorithm(String keyManagerAlgorithm)
void	setKeyPassword(String keyPassword)
void	setKeyStore(String name)
void	setKeyStorePassword(String storePassword)
void	setKeyStoreType(String keystoreType)
void	setProtocolHandler(String protocolHandler)
void	setProvider(Provider provider)
void	setRequireClientAuthentication(boolean requireClientAuthentication) If a server socket is constructed directly (see TlsConfiguration) then this flag will control whether client authenticatin is required.
void	setSecurityProviderFactory(SecurityProviderFactory spFactory)
void	setSslType(String sslType)
void	setTrustManagerAlgorithm(String trustManagerAlgorithm)
void	setTrustManagerFactory(TrustManagerFactory trustManagerFactory)
void	setTrustStore(String name)
void	setTrustStorePassword(String trustStorePassword)
void	setTrustStoreType(String trustStoreType)

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_KEYSTORE

public static final String DEFAULT_KEYSTORE

See Also:

Constant Field Values

DEFAULT_KEYSTORE_TYPE

public static final String DEFAULT_KEYSTORE_TYPE

DEFAULT_SSL_TYPE

public static final String DEFAULT_SSL_TYPE

See Also:

Constant Field Values

JSSE_NAMESPACE

public static final String JSSE_NAMESPACE

See Also:

Constant Field Values

Constructor Detail

TlsConfiguration

public TlsConfiguration(String keyStore)

Support for TLS connections with a given initial value for the key store

Parameters:

keyStore - initial value for the key store

Method Detail

initialise

public void initialise(boolean anon,
                       String namespace)
                throws CreateException

Parameters:

anon - If the connection is anonymous then we don't care about client keys

namespace - Namespace to use for global properties (for JSSE use JSSE_NAMESPACE)

Throws:

CreateException - ON initialisation problems

getSocketFactory

public SSLSocketFactory getSocketFactory()
                                  throws NoSuchAlgorithmException,
                                         KeyManagementException

Throws:

NoSuchAlgorithmException

KeyManagementException

getServerSocketFactory

public SSLServerSocketFactory getServerSocketFactory()
                                              throws NoSuchAlgorithmException,
                                                     KeyManagementException

Throws:

NoSuchAlgorithmException

KeyManagementException

getSslContext

public SSLContext getSslContext()
                         throws NoSuchAlgorithmException,
                                KeyManagementException

Throws:

NoSuchAlgorithmException

KeyManagementException

getSslType

public String getSslType()

setSslType

public void setSslType(String sslType)

getProvider

public Provider getProvider()

setProvider

public void setProvider(Provider provider)

getProtocolHandler

public String getProtocolHandler()

Specified by:

getProtocolHandler in interface TlsProtocolHandler

setProtocolHandler

public void setProtocolHandler(String protocolHandler)

Specified by:

setProtocolHandler in interface TlsProtocolHandler

getSecurityProviderFactory

public SecurityProviderFactory getSecurityProviderFactory()

setSecurityProviderFactory

public void setSecurityProviderFactory(SecurityProviderFactory spFactory)

getKeyStore

public String getKeyStore()

Specified by:

getKeyStore in interface TlsDirectKeyStore

Returns:

The location (resolved relative to the current classpath and file system, if possible) of the keystore that contains public certificates and private keys for identification.

setKeyStore

public void setKeyStore(String name)
                 throws IOException

Specified by:

setKeyStore in interface TlsDirectKeyStore

Parameters:

name - The location of the keystore that contains public certificates and private keys for identification.

Throws:

IOException - If the location cannot be resolved via the file system or classpath

getKeyPassword

public String getKeyPassword()

Specified by:

getKeyPassword in interface TlsDirectKeyStore

Returns:

The password used to protect the private key(s)

setKeyPassword

public void setKeyPassword(String keyPassword)

Specified by:

setKeyPassword in interface TlsDirectKeyStore

Parameters:

keyPassword - The password used to protect the private key(s)

getKeyStorePassword

public String getKeyStorePassword()

Specified by:

getKeyStorePassword in interface TlsDirectKeyStore

Returns:

The password used to protect the keystore itself

setKeyStorePassword

public void setKeyStorePassword(String storePassword)

Specified by:

setKeyStorePassword in interface TlsDirectKeyStore

Parameters:

storePassword - The password used to protect the keystore itself

getKeyStoreType

public String getKeyStoreType()

Specified by:

getKeyStoreType in interface TlsDirectKeyStore

Returns:

The type of keystore used in TlsDirectKeyStore.getKeyStore()

setKeyStoreType

public void setKeyStoreType(String keystoreType)

Specified by:

setKeyStoreType in interface TlsDirectKeyStore

Parameters:

keystoreType - The type of keystore used in TlsDirectKeyStore.setKeyStore(String)

getKeyManagerAlgorithm

public String getKeyManagerAlgorithm()

Specified by:

getKeyManagerAlgorithm in interface TlsDirectKeyStore

Returns:

The algorithm used by the key store. The default comes from {

setKeyManagerAlgorithm

public void setKeyManagerAlgorithm(String keyManagerAlgorithm)

Specified by:

setKeyManagerAlgorithm in interface TlsDirectKeyStore

Parameters:

keyManagerAlgorithm - The algorithm used by the key store. The default comes from {

getKeyManagerFactory

public KeyManagerFactory getKeyManagerFactory()

Specified by:

getKeyManagerFactory in interface TlsDirectKeyStore

Returns:

A source of key stores generated from the parameters supplied here.

getClientKeyStore

public String getClientKeyStore()

Specified by:

getClientKeyStore in interface TlsIndirectKeyStore

Returns:

The location (resolved relative to the current classpath and file system, if possible) of the keystore that contains public certificates and private keys for identification.

setClientKeyStore

public void setClientKeyStore(String name)
                       throws IOException

Specified by:

setClientKeyStore in interface TlsIndirectKeyStore

Parameters:

name - The location of the keystore that contains public certificates and private keys for identification.

Throws:

IOException - If the location cannot be resolved via the file system or classpath

getClientKeyStorePassword

public String getClientKeyStorePassword()

Specified by:

getClientKeyStorePassword in interface TlsIndirectKeyStore

Returns:

The password used to protect the keystore itself

setClientKeyStorePassword

public void setClientKeyStorePassword(String clientKeyStorePassword)

Specified by:

setClientKeyStorePassword in interface TlsIndirectKeyStore

Parameters:

clientKeyStorePassword - The password used to protect the keystore itself

setClientKeyStoreType

public void setClientKeyStoreType(String clientKeyStoreType)

Specified by:

setClientKeyStoreType in interface TlsIndirectKeyStore

getClientKeyStoreType

public String getClientKeyStoreType()

Specified by:

getClientKeyStoreType in interface TlsIndirectKeyStore

Returns:

The type of keystore used in TlsIndirectKeyStore.setClientKeyStore(String)

getTrustStore

public String getTrustStore()

Specified by:

getTrustStore in interface TlsIndirectTrustStore

Returns:

The location (resolved relative to the current classpath and file system, if possible) of the keystore that contains public certificates of trusted servers.

setTrustStore

public void setTrustStore(String name)
                   throws IOException

Specified by:

setTrustStore in interface TlsIndirectTrustStore

Parameters:

name - The location of the keystore that contains public certificates of trusted servers.

Throws:

IOException - If the location cannot be resolved via the file system or classpath

getTrustStorePassword

public String getTrustStorePassword()

Specified by:

getTrustStorePassword in interface TlsIndirectTrustStore

Returns:

The password used to protected the trust store defined in TlsIndirectTrustStore.getTrustStore()

setTrustStorePassword

public void setTrustStorePassword(String trustStorePassword)

Specified by:

setTrustStorePassword in interface TlsIndirectTrustStore

Parameters:

trustStorePassword - The password used to protected the trust store defined in TlsIndirectTrustStore.setTrustStore(String)

getTrustStoreType

public String getTrustStoreType()

Specified by:

getTrustStoreType in interface TlsDirectTrustStore

Returns:

The type of keystore used to implement the trust store defined in TlsIndirectTrustStore.getTrustStore()

setTrustStoreType

public void setTrustStoreType(String trustStoreType)

Specified by:

setTrustStoreType in interface TlsDirectTrustStore

Parameters:

trustStoreType - The type of keystore used to implement the trust store defined in TlsIndirectTrustStore.setTrustStore(String)

getTrustManagerAlgorithm

public String getTrustManagerAlgorithm()

Specified by:

getTrustManagerAlgorithm in interface TlsDirectTrustStore

Returns:

The algorithm used by the trust store. The default comes from AutoDiscoverySecurityProviderFactory

setTrustManagerAlgorithm

public void setTrustManagerAlgorithm(String trustManagerAlgorithm)

Specified by:

setTrustManagerAlgorithm in interface TlsDirectTrustStore

Parameters:

trustManagerAlgorithm - The algorithm used by the trust store. The default comes from AutoDiscoverySecurityProviderFactory

getTrustManagerFactory

public TrustManagerFactory getTrustManagerFactory()

Specified by:

getTrustManagerFactory in interface TlsDirectTrustStore

Returns:

Either the factory defined by TlsDirectTrustStore.setTrustManagerFactory(TrustManagerFactory) or one constructed from the parameters in this interface (TlsDirectTrustStore.setTrustStoreType(String) etc).

setTrustManagerFactory

public void setTrustManagerFactory(TrustManagerFactory trustManagerFactory)

Specified by:

setTrustManagerFactory in interface TlsDirectTrustStore

Parameters:

trustManagerFactory - The source of trust information if the store is accessed directly (some connectors generate trust stores indirectly through System properties in which case this value will be ignored - see TlsConfiguration).

isExplicitTrustStoreOnly

public boolean isExplicitTrustStoreOnly()

Description copied from interface: TlsDirectTrustStore

If the trust store is undefined and the trust store generated via System properties then the key store certificates defined via TODO can be used as a source of trust information.

Specified by:

isExplicitTrustStoreOnly in interface TlsDirectTrustStore

Returns:

true if the key store data should not be used when a trust store is otherwise undefined

setExplicitTrustStoreOnly

public void setExplicitTrustStoreOnly(boolean explicitTrustStoreOnly)

Description copied from interface: TlsDirectTrustStore

If the trust store is undefined and the trust store generated via System properties then the key store certificates defined via TODO can be used as a source of trust information.

Specified by:

setExplicitTrustStoreOnly in interface TlsDirectTrustStore

Parameters:

explicitTrustStoreOnly - true if the key store data should not be used when a trust store is otherwise undefined

isRequireClientAuthentication

public boolean isRequireClientAuthentication()

Description copied from interface: TlsDirectTrustStore

If a server socket is constructed directly (see TlsConfiguration) then this flag will control whether client authenticatin is required. This does not apply to client connections.

Specified by:

isRequireClientAuthentication in interface TlsDirectTrustStore

Returns:

true if clients must be authenticated

setRequireClientAuthentication

public void setRequireClientAuthentication(boolean requireClientAuthentication)

Description copied from interface: TlsDirectTrustStore

If a server socket is constructed directly (see TlsConfiguration) then this flag will control whether client authenticatin is required. This does not apply to client connections.

Specified by:

setRequireClientAuthentication in interface TlsDirectTrustStore

Parameters:

requireClientAuthentication - true if clients must be authenticated