org.eclipse.paho.client.mqttv3.internal.security
Class SSLSocketFactoryFactory

java.lang.Object
  extended by org.eclipse.paho.client.mqttv3.internal.security.SSLSocketFactoryFactory

public class SSLSocketFactoryFactory
extends Object

An SSLSocketFactoryFactory provides a socket factory and a server socket factory that then can be used to create SSL client sockets or SSL server sockets.

The SSLSocketFactoryFactory is configured using IBM SSL properties, i.e. properties of the format "com.ibm.ssl.propertyName", e.g. "com.ibm.ssl.keyStore". The class supports multiple configurations, each configuration is identified using a name or configuration ID. The configuration ID with "null" is used as a default configuration. When a socket factory is being created for a given configuration, properties of that configuration are first picked. If a property is not defined there, then that property is looked up in the default configuration. Finally, if a property element is still not found, then the corresponding system property is inspected, i.e. javax.net.ssl.keyStore. If the system property is not set either, then the system's default value is used (if available) or an exception is thrown.

The SSLSocketFacotryFactory can be reconfigured at any time. A reconfiguration does not affect existing socket factories.

All properties share the same key space; i.e. the configuration ID is not part of the property keys.

The methods should be called in the following order:

  1. isSupportedOnJVM(): to check whether this class is supported on the runtime platform. Not all runtimes support SSL/TLS.
  2. SSLSocketFactoryFactory(): the constructor. Clients (in the same JVM) may share an SSLSocketFactoryFactory, or have one each.
  3. initialize(properties, configID): to initialize this object with the required SSL properties for a configuration. This may be called multiple times, once for each required configuration.It may be called again to change the required SSL properties for a particular configuration
  4. getEnabledCipherSuites(configID): to later set the enabled cipher suites on the socket [see below].


Field Summary
static String CIPHERSUITES
           
static String CLIENTAUTH
           
static String DEFAULT_PROTOCOL
           
static String JSSEPROVIDER
           
static String KEYSTORE
           
static String KEYSTOREMGR
           
static String KEYSTOREPROVIDER
           
static String KEYSTOREPWD
           
static String KEYSTORETYPE
           
static String SSLPROTOCOL
          Property keys specific to the client).
static String SYSKEYMGRALGO
           
static String SYSKEYSTORE
          Property keys used for java system properties
static String SYSKEYSTOREPWD
           
static String SYSKEYSTORETYPE
           
static String SYSTRUSTMGRALGO
           
static String SYSTRUSTSTORE
           
static String SYSTRUSTSTOREPWD
           
static String SYSTRUSTSTORETYPE
           
static String TRUSTSTORE
           
static String TRUSTSTOREMGR
           
static String TRUSTSTOREPROVIDER
           
static String TRUSTSTOREPWD
           
static String TRUSTSTORETYPE
           
 
Constructor Summary
SSLSocketFactoryFactory()
          Create new instance of class.
SSLSocketFactoryFactory(Logger logger)
          Create new instance of class.
 
Method Summary
 SSLSocketFactory createSocketFactory(String configID)
          Returns an SSL socket factory for the given configuration.
static char[] deObfuscate(String ePassword)
          The inverse operation of obfuscate: returns a cleartext password that was previously obfuscated using the XOR scrambler.
 boolean getClientAuthentication(String configID)
          Returns whether client authentication is required.
 Properties getConfiguration(String configID)
          Returns the configuration of the SSLSocketFactoryFactory for a given configuration.
 String[] getEnabledCipherSuites(String configID)
          Returns an array with the enabled ciphers.
 String getJSSEProvider(String configID)
          Gets the JSSE provider of the indicated configuration
 String getKeyManager(String configID)
          Gets the key manager algorithm that is used.
 String getKeyStore(String configID)
          Gets the name of the keystore file that is used.
 char[] getKeyStorePassword(String configID)
          Gets the plain-text password that is used for the keystore.
 String getKeyStoreProvider(String configID)
          Gets the keystore provider.
 String getKeyStoreType(String configID)
          Gets the type of keystore.
 String getSSLProtocol(String configID)
          Gets the SSL protocol variant of the indicated configuration or the default configuration.
 String getTrustManager(String configID)
          Gets the trust manager algorithm that is used.
 String getTrustStore(String configID)
          Gets the name of the truststore file that is used.
 char[] getTrustStorePassword(String configID)
          Gets the plain-text password that is used for the truststore.
 String getTrustStoreProvider(String configID)
          Gets the truststore provider.
 String getTrustStoreType(String configID)
          Gets the type of truststore.
 void initialize(Properties props, String configID)
          Initializes the SSLSocketFactoryFactory with the provided properties for the provided configuration.
static boolean isSupportedOnJVM()
          Not all of the JVM/Platforms support all of its security features.
 void merge(Properties props, String configID)
          Merges the given IBM SSL properties into the existing configuration, overwriting existing properties.
static String obfuscate(char[] password)
          Obfuscates the password using a simple and not very secure XOR mechanism.
static String packCipherSuites(String[] ciphers)
          Converts an array of ciphers into a single String.
 boolean remove(String configID)
          Remove the configuration of a given configuration identifier.
static byte[] toByte(char[] c)
          Convert char array to byte array, where each char is split into two bytes.
static char[] toChar(byte[] b)
          Convert byte array to char array, where each char is constructed from two bytes.
static String[] unpackCipherSuites(String ciphers)
          Inverse operation of packCipherSuites: converts a string of cipher names into an array of cipher names
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SSLPROTOCOL

public static final String SSLPROTOCOL
Property keys specific to the client).

See Also:
Constant Field Values

JSSEPROVIDER

public static final String JSSEPROVIDER
See Also:
Constant Field Values

KEYSTORE

public static final String KEYSTORE
See Also:
Constant Field Values

KEYSTOREPWD

public static final String KEYSTOREPWD
See Also:
Constant Field Values

KEYSTORETYPE

public static final String KEYSTORETYPE
See Also:
Constant Field Values

KEYSTOREPROVIDER

public static final String KEYSTOREPROVIDER
See Also:
Constant Field Values

KEYSTOREMGR

public static final String KEYSTOREMGR
See Also:
Constant Field Values

TRUSTSTORE

public static final String TRUSTSTORE
See Also:
Constant Field Values

TRUSTSTOREPWD

public static final String TRUSTSTOREPWD
See Also:
Constant Field Values

TRUSTSTORETYPE

public static final String TRUSTSTORETYPE
See Also:
Constant Field Values

TRUSTSTOREPROVIDER

public static final String TRUSTSTOREPROVIDER
See Also:
Constant Field Values

TRUSTSTOREMGR

public static final String TRUSTSTOREMGR
See Also:
Constant Field Values

CIPHERSUITES

public static final String CIPHERSUITES
See Also:
Constant Field Values

CLIENTAUTH

public static final String CLIENTAUTH
See Also:
Constant Field Values

SYSKEYSTORE

public static final String SYSKEYSTORE
Property keys used for java system properties

See Also:
Constant Field Values

SYSKEYSTORETYPE

public static final String SYSKEYSTORETYPE
See Also:
Constant Field Values

SYSKEYSTOREPWD

public static final String SYSKEYSTOREPWD
See Also:
Constant Field Values

SYSTRUSTSTORE

public static final String SYSTRUSTSTORE
See Also:
Constant Field Values

SYSTRUSTSTORETYPE

public static final String SYSTRUSTSTORETYPE
See Also:
Constant Field Values

SYSTRUSTSTOREPWD

public static final String SYSTRUSTSTOREPWD
See Also:
Constant Field Values

SYSKEYMGRALGO

public static final String SYSKEYMGRALGO
See Also:
Constant Field Values

SYSTRUSTMGRALGO

public static final String SYSTRUSTMGRALGO
See Also:
Constant Field Values

DEFAULT_PROTOCOL

public static final String DEFAULT_PROTOCOL
See Also:
Constant Field Values
Constructor Detail

SSLSocketFactoryFactory

public SSLSocketFactoryFactory()
Create new instance of class. Constructor used by clients.


SSLSocketFactoryFactory

public SSLSocketFactoryFactory(Logger logger)
Create new instance of class. Constructor used by the broker.

Method Detail

isSupportedOnJVM

public static boolean isSupportedOnJVM()
                                throws LinkageError,
                                       ExceptionInInitializerError
Not all of the JVM/Platforms support all of its security features. This method determines if is supported.

Returns:
whether dependent classes can be instantiated on the current JVM/platform.
Throws:
Error - if any unexpected error encountered whilst checking. Note this should not be a ClassNotFoundException, which should cause the method to return false.
LinkageError
ExceptionInInitializerError

toChar

public static char[] toChar(byte[] b)
Convert byte array to char array, where each char is constructed from two bytes.

Parameters:
b - byte array
Returns:
char array

toByte

public static byte[] toByte(char[] c)
Convert char array to byte array, where each char is split into two bytes.

Parameters:
c - char array
Returns:
byte array

obfuscate

public static String obfuscate(char[] password)
Obfuscates the password using a simple and not very secure XOR mechanism. This should not be used for cryptographical purpose, it's a simple scrambler to obfuscate clear-text passwords.

Parameters:
password - The password to be encrypted, as a char[] array.
Returns:
An obfuscated password as a String.
See Also:
deObfuscate(java.lang.String)

deObfuscate

public static char[] deObfuscate(String ePassword)
The inverse operation of obfuscate: returns a cleartext password that was previously obfuscated using the XOR scrambler.

Parameters:
ePassword - An obfuscated password.
Returns:
An array of char, containing the clear text password.
See Also:
obfuscate(char[])

packCipherSuites

public static String packCipherSuites(String[] ciphers)
Converts an array of ciphers into a single String.

Parameters:
ciphers - The array of cipher names.
Returns:
A string containing the name of the ciphers, separated by comma.

unpackCipherSuites

public static String[] unpackCipherSuites(String ciphers)
Inverse operation of packCipherSuites: converts a string of cipher names into an array of cipher names

Parameters:
ciphers - A list of ciphers, separated by comma.
Returns:
An array of string, each string containing a single cipher name.

initialize

public void initialize(Properties props,
                       String configID)
                throws IllegalArgumentException
Initializes the SSLSocketFactoryFactory with the provided properties for the provided configuration.

Parameters:
props - A properties object containing IBM SSL properties that are qualified by one or more configuration identifiers.
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Throws:
IllegalArgumentException - if any of the properties is not a valid IBM SSL property key.

merge

public void merge(Properties props,
                  String configID)
           throws IllegalArgumentException
Merges the given IBM SSL properties into the existing configuration, overwriting existing properties. This method is used to selectively change properties for a given configuration. The method throws an IllegalArgumentException if any of the properties is not a valid IBM SSL property key.

Parameters:
props - A properties object containing IBM SSL properties
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Throws:
IllegalArgumentException - if any of the properties is not a valid IBM SSL property key.

remove

public boolean remove(String configID)
Remove the configuration of a given configuration identifier.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
true, if the configuation could be removed.

getConfiguration

public Properties getConfiguration(String configID)
Returns the configuration of the SSLSocketFactoryFactory for a given configuration. Note that changes in the property are reflected in the SSLSocketFactoryFactory.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
A property object containing the current configuration of the SSLSocketFactoryFactory. Note that it could be null.

getSSLProtocol

public String getSSLProtocol(String configID)
Gets the SSL protocol variant of the indicated configuration or the default configuration.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The SSL protocol variant.

getJSSEProvider

public String getJSSEProvider(String configID)
Gets the JSSE provider of the indicated configuration

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The JSSE provider.

getKeyStore

public String getKeyStore(String configID)
Gets the name of the keystore file that is used.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The name of the file that contains the keystore.

getKeyStorePassword

public char[] getKeyStorePassword(String configID)
Gets the plain-text password that is used for the keystore.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The password in plain text.

getKeyStoreType

public String getKeyStoreType(String configID)
Gets the type of keystore.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The keystore type.

getKeyStoreProvider

public String getKeyStoreProvider(String configID)
Gets the keystore provider.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The name of the keystore provider.

getKeyManager

public String getKeyManager(String configID)
Gets the key manager algorithm that is used.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The key manager algorithm.

getTrustStore

public String getTrustStore(String configID)
Gets the name of the truststore file that is used.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The name of the file that contains the truststore.

getTrustStorePassword

public char[] getTrustStorePassword(String configID)
Gets the plain-text password that is used for the truststore.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The password in plain text.

getTrustStoreType

public String getTrustStoreType(String configID)
Gets the type of truststore.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The truststore type.

getTrustStoreProvider

public String getTrustStoreProvider(String configID)
Gets the truststore provider.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The name of the truststore provider.

getTrustManager

public String getTrustManager(String configID)
Gets the trust manager algorithm that is used.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
The trust manager algorithm.

getEnabledCipherSuites

public String[] getEnabledCipherSuites(String configID)
Returns an array with the enabled ciphers.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
an array with the enabled ciphers

getClientAuthentication

public boolean getClientAuthentication(String configID)
Returns whether client authentication is required.

Parameters:
configID - The configuration identifier for selecting a configuration or null for the default configuration.
Returns:
true, if clients are required to authenticate, false otherwise.

createSocketFactory

public SSLSocketFactory createSocketFactory(String configID)
                                     throws MqttSecurityException
Returns an SSL socket factory for the given configuration. If no SSLProtocol is already set, uses DEFAULT_PROTOCOL. Throws IllegalArgumentException if the socket factory could not be created due to underlying configuration problems.

Parameters:
configID - The configuration identifier for selecting a configuration.
Returns:
An SSLSocketFactory
Throws:
MqttDirectException
MqttSecurityException
See Also:
DEFAULT_PROTOCOL


Copyright © 2013. All Rights Reserved.