| 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
org.mule.api.security.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
org.mule.api.security.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
org.mule.api.security.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(TlsConfigurationjava.util.Properties) the "indirect" properties are supplied as "direct" values, meaning that the "indirect"
socket factory can be retrieved from
TlsConfiguration.getKeyManagerFactory() . It just works.
|
