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 {@link org.mule.api.security.TlsIndirectTrustStore}, {@link TlsDirectTrustStore}, {@link TlsDirectKeyStore} and {@link TlsIndirectKeyStore} should provide guidance to individualproperties. 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 {@link org.mule.api.security.TlsIndirectTrustStore}, {@link TlsDirectTrustStore}, {@link TlsDirectKeyStore} and {@link TlsIndirectKeyStore}, and then forward calls to the interfaces to an instance of this class).
For setting System properties (and reading them) use {@link TlsPropertiesMapper}. This can take a "namespace" which can then be used by {@link TlsPropertiesSocketFactory} toconstruct 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:
- {@link TlsDirectTrustStore}
- Used to generate trust store directly and indirectly for all TLS/SSL conections via System properties
- {@link TlsDirectKeyStore}
- Used to generate key store directly
- {@link 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 {@link org.mule.api.security.TlsIndirectTrustStore}(a superclass of {@link TlsDirectTrustStore}) and relied on {@link TlsIndirectKeyStore} from the SSL configuration. For continuity theseinterfaces 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 {@link TlsPropertiesSocketFactory}) we continue to use properties and the "indirect" interface. Note also that the mapping in {@link TlsPropertiesMapper} correctly handles the asymmetry, so an initial call to{@link TlsConfiguration} uses the keystore defined via {@link TlsDirectKeyStore}, but when a {@link TlsConfiguration} is retrieved from System proerties using{@link TlsPropertiesMapper#readFromProperties(TlsConfiguration,java.util.Properties)}the "indirect" properties are supplied as "direct" values, meaning that the "indirect" socket factory can be retrieved from {@link #getKeyManagerFactory()}. It just works.