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

Class SSLSocketFactoryFactory

java.lang.Object

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

public class SSLSocketFactoryFactory
extends java.lang.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].

• For an MQTT server:
1. getKeyStore(configID): Optionally, to check that if there is no keystore, then that all the enabled cipher suits are anonymous.
2. createServerSocketFactory(configID): to create an SSLServerSocketFactory.
3. getClientAuthentication(configID): to later set on the SSLServerSocket (itself created from the SSLServerSocketFactory) whether client authentication is needed.
• For an MQTT client:
1. createSocketFactory(configID): to create an SSLSocketFactory.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CIPHERSUITES
static java.lang.String	CLIENTAUTH
static java.lang.String	DEFAULT_PROTOCOL
static java.lang.String	JSSEPROVIDER
static java.lang.String	KEYSTORE
static java.lang.String	KEYSTOREMGR
static java.lang.String	KEYSTOREPROVIDER
static java.lang.String	KEYSTOREPWD
static java.lang.String	KEYSTORETYPE
static java.lang.String	SSLPROTOCOL Property keys specific to the client).
static java.lang.String	SYSKEYMGRALGO
static java.lang.String	SYSKEYSTORE Property keys used for java system properties
static java.lang.String	SYSKEYSTOREPWD
static java.lang.String	SYSKEYSTORETYPE
static java.lang.String	SYSTRUSTMGRALGO
static java.lang.String	SYSTRUSTSTORE
static java.lang.String	SYSTRUSTSTOREPWD
static java.lang.String	SYSTRUSTSTORETYPE
static java.lang.String	TRUSTSTORE
static java.lang.String	TRUSTSTOREMGR
static java.lang.String	TRUSTSTOREPROVIDER
static java.lang.String	TRUSTSTOREPWD
static java.lang.String	TRUSTSTORETYPE

Constructor Summary

Constructors

Constructor and Description
SSLSocketFactoryFactory() Create new instance of class.
SSLSocketFactoryFactory(Logger logger) Create new instance of class.

Method Summary

Modifier and Type	Method and Description
javax.net.ssl.SSLSocketFactory	createSocketFactory(java.lang.String configID) Returns an SSL socket factory for the given configuration.
static char[]	deObfuscate(java.lang.String ePassword) The inverse operation of obfuscate: returns a cleartext password that was previously obfuscated using the XOR scrambler.
boolean	getClientAuthentication(java.lang.String configID) Returns whether client authentication is required.
java.util.Properties	getConfiguration(java.lang.String configID) Returns the configuration of the SSLSocketFactoryFactory for a given configuration.
java.lang.String[]	getEnabledCipherSuites(java.lang.String configID) Returns an array with the enabled ciphers.
java.lang.String	getJSSEProvider(java.lang.String configID) Gets the JSSE provider of the indicated configuration
java.lang.String	getKeyManager(java.lang.String configID) Gets the key manager algorithm that is used.
java.lang.String	getKeyStore(java.lang.String configID) Gets the name of the keystore file that is used.
char[]	getKeyStorePassword(java.lang.String configID) Gets the plain-text password that is used for the keystore.
java.lang.String	getKeyStoreProvider(java.lang.String configID) Gets the keystore provider.
java.lang.String	getKeyStoreType(java.lang.String configID) Gets the type of keystore.
java.lang.String	getSSLProtocol(java.lang.String configID) Gets the SSL protocol variant of the indicated configuration or the default configuration.
java.lang.String	getTrustManager(java.lang.String configID) Gets the trust manager algorithm that is used.
java.lang.String	getTrustStore(java.lang.String configID) Gets the name of the truststore file that is used.
char[]	getTrustStorePassword(java.lang.String configID) Gets the plain-text password that is used for the truststore.
java.lang.String	getTrustStoreProvider(java.lang.String configID) Gets the truststore provider.
java.lang.String	getTrustStoreType(java.lang.String configID) Gets the type of truststore.
void	initialize(java.util.Properties props, java.lang.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(java.util.Properties props, java.lang.String configID) Merges the given IBM SSL properties into the existing configuration, overwriting existing properties.
static java.lang.String	obfuscate(char[] password) Obfuscates the password using a simple and not very secure XOR mechanism.
static java.lang.String	packCipherSuites(java.lang.String[] ciphers) Converts an array of ciphers into a single String.
boolean	remove(java.lang.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 java.lang.String[]	unpackCipherSuites(java.lang.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

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SSLPROTOCOL

public static final java.lang.String SSLPROTOCOL

Property keys specific to the client).

See Also:

Constant Field Values

JSSEPROVIDER

public static final java.lang.String JSSEPROVIDER

See Also:

Constant Field Values

KEYSTORE

public static final java.lang.String KEYSTORE

See Also:

Constant Field Values

KEYSTOREPWD

public static final java.lang.String KEYSTOREPWD

See Also:

Constant Field Values

KEYSTORETYPE

public static final java.lang.String KEYSTORETYPE

See Also:

Constant Field Values

KEYSTOREPROVIDER

public static final java.lang.String KEYSTOREPROVIDER

See Also:

Constant Field Values

KEYSTOREMGR

public static final java.lang.String KEYSTOREMGR

See Also:

Constant Field Values

TRUSTSTORE

public static final java.lang.String TRUSTSTORE

See Also:

Constant Field Values

TRUSTSTOREPWD

public static final java.lang.String TRUSTSTOREPWD

See Also:

Constant Field Values

TRUSTSTORETYPE

public static final java.lang.String TRUSTSTORETYPE

See Also:

Constant Field Values

TRUSTSTOREPROVIDER

public static final java.lang.String TRUSTSTOREPROVIDER

See Also:

Constant Field Values

TRUSTSTOREMGR

public static final java.lang.String TRUSTSTOREMGR

See Also:

Constant Field Values

CIPHERSUITES

public static final java.lang.String CIPHERSUITES

See Also:

Constant Field Values

CLIENTAUTH

public static final java.lang.String CLIENTAUTH

See Also:

Constant Field Values

SYSKEYSTORE

public static final java.lang.String SYSKEYSTORE

Property keys used for java system properties

See Also:

Constant Field Values

SYSKEYSTORETYPE

public static final java.lang.String SYSKEYSTORETYPE

See Also:

Constant Field Values

SYSKEYSTOREPWD

public static final java.lang.String SYSKEYSTOREPWD

See Also:

Constant Field Values

SYSTRUSTSTORE

public static final java.lang.String SYSTRUSTSTORE

See Also:

Constant Field Values

SYSTRUSTSTORETYPE

public static final java.lang.String SYSTRUSTSTORETYPE

See Also:

Constant Field Values

SYSTRUSTSTOREPWD

public static final java.lang.String SYSTRUSTSTOREPWD

See Also:

Constant Field Values

SYSKEYMGRALGO

public static final java.lang.String SYSKEYMGRALGO

See Also:

Constant Field Values

SYSTRUSTMGRALGO

public static final java.lang.String SYSTRUSTMGRALGO

See Also:

Constant Field Values

DEFAULT_PROTOCOL

public static final java.lang.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 java.lang.LinkageError,
                                       java.lang.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:

java.lang.Error - if any unexpected error encountered whilst checking. Note this should not be a ClassNotFoundException, which should cause the method to return false.

java.lang.LinkageError

java.lang.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 java.lang.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(java.lang.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 java.lang.String packCipherSuites(java.lang.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 java.lang.String[] unpackCipherSuites(java.lang.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(java.util.Properties props,
                       java.lang.String configID)
                throws java.lang.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:

java.lang.IllegalArgumentException - if any of the properties is not a valid IBM SSL property key.

merge

public void merge(java.util.Properties props,
                  java.lang.String configID)
           throws java.lang.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:

java.lang.IllegalArgumentException - if any of the properties is not a valid IBM SSL property key.

remove

public boolean remove(java.lang.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 java.util.Properties getConfiguration(java.lang.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 java.lang.String getSSLProtocol(java.lang.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 java.lang.String getJSSEProvider(java.lang.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 java.lang.String getKeyStore(java.lang.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(java.lang.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 java.lang.String getKeyStoreType(java.lang.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 java.lang.String getKeyStoreProvider(java.lang.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 java.lang.String getKeyManager(java.lang.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 java.lang.String getTrustStore(java.lang.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(java.lang.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 java.lang.String getTrustStoreType(java.lang.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 java.lang.String getTrustStoreProvider(java.lang.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 java.lang.String getTrustManager(java.lang.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 java.lang.String[] getEnabledCipherSuites(java.lang.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(java.lang.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 javax.net.ssl.SSLSocketFactory createSocketFactory(java.lang.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