org.mule.api.security.tls
Class TlsConfiguration

java.lang.Object
  extended by 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 proeprties 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 {

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 {

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 (TlsIndirectTrustStore.setTrustStore(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


Copyright © 2003-2009 MuleSource, Inc.. All Rights Reserved.