TlsConfiguration (Mule ESB 2.2.1 API)
Keywords: org.mule.api.security.tls.TlsConfiguration class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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