Table
of Contents |
Previous
|
Next
There are three primary scenarios for how to configure and use an SSL connection:
- Server authentication - When a client connects to the micro broker,
the client verifies the micro broker's identity. When using this mode,
a client can be sure that is talking to a trusted server, but the server
does not know the identity of the client. In this scenario, the micro broker
will present a X509 certificate (kept in a keystore) to the client during
the SSL handshake, and the client will verify the certificate according
to its trusted material (kept in a truststore).
- Mutual authentication - Similar to server authentication, but
the micro broker also authenticates the client's identity, so that both
parties know who they are communicating with. Both client and the micro
broker will keep their certificates and trusted material in their respective
keystores and truststores.
- Using no authentication at all - This scenario is vulnerable
to "man in the middle" attacks, as neither the client or the
micro broker knows the identity of the other party. This mode is inherently
less secure than the other methods, and is not recommended for production
use.
It is important to note the the term "authentication" relates
specifically to the authentication of the client and/or the micro broker
to establish an encrypted network connection, that is, authentication on
the wire. It should not be confused with the authentication at the messaging
level, which is used to determine whether or not a particular client is
who they claim to be and whether they are allowed to make use of broker’s
facilities, such as to publish or subscribe to topics.
The command line tool 'keytool' is a key and certificate management utility
that can be used for the administration of key and trust stores.
SSL configuration in the micro broker
There are two entities that support SSL configuration in the micro broker:
- Listener: A TCP socket where the micro broker listens to
incoming client connections.
- Pipe: In the bridge, it represents the owning entity of
a connection between the micro broker and a remote end point (another micro
broker, for instance).
SSL can be configured for the micro broker in one of several ways. The
micro broker uses these configuration options in the following order:
- Listener- or Pipe-specific settings - the specific listener or
bridge pipe can be configured via SSLDefinition interface.
- Broker-specific settings - broker-wide settings can be configured
with an SSLDefinition.
- Lotus® Expeditor settings - if an Expeditor platform key store
is available, it will be used.
- Use JVM settings - There are a number of standard Java™ system
properties that can be used to configure key and trust stores.
Please refer to
IBM
Lotus Expeditor InfoCenter
for further information about the list of SSL configuration settings in
the micro broker.
For SSL to work a key store must be specified. DesktopEE supports a limited
set of key store types. It is important to note that DesktopEE and
Java SE are incompatible regarding keystore formats: keystore files
that are created by the Java 2 SE 5.0 VM are not compatible with DesktopEE.
Likewise, keystore files created with DesktopEE are not compatible with
Java 2 SE 5.0. For this reason, IBM Lotus Expeditor will maintain one keystore
file per VM. Because of this, when switching VMs, you must reset all the
passwords that were stored in the keystore and the keystore password itself.
None of the data stored in one VM's keystore file will be transferred to
the other VM's keystore file. It is important to note that it is possible
to have two completely different sets of stored credentials; one accessible
only to DesktopEE and one accessible only to Java 2 SE 5.0.
Next we will show how to configure SSL listeners and bridge pipes in the
micro broker using the API offered by SSLDefinition interface in a server
authentication scenario. In that scenario, the micro broker will configure
a keystore for the listeners, and bridge pipes will configure a truststore
with trusted material of the remote server (for example, certificate of
the remote micro broker).
Listeners
The micro broker can accept incoming encrypted connections using SSL protocol.
Once the connection is established, all the data stream between the client
application and the micro broker will flow securely (encrypted) over the
network.
It is important to note that a SSL listener needs a keystore to start up.
The following sample code creates a broker with a default SSL listener
(if not specified, default SSL port is 8883):
import com.ibm.micro.admin.BrokerDefinition;
import com.ibm.micro.admin.BrokerFactory;
import com.ibm.micro.admin.LocalBroker;
import com.ibm.micro.admin.ServerSSLDefinition;
BrokerFactory factory = BrokerFactory.INSTANCE;
String brokerName = "FirstBroker";
String dataDirectory = ("path_to_broker_data_directory");
if (!factory.exists(brokerName)) {
BrokerDefinition brokerDef= factory.createBrokerDefinition(brokerName);
brokerDef.setDataDirectory( dataDirectory );
ServerSSLDefinition sslDef = brokerDef.createSSLDefinition();
sslDef.setKeyStore("path_to_keystore");
sslDef.setKeyStorePassword("123456".toCharArray());
brokerDef.setDefaultListenerSSLDefinition(sslDef);
brokerDef.setDefaultListenerSecure(true);
LocalBroker broker = factory.create(brokerDef);
broker.start();
} else {
LocalBroker broker = factory.getByName(brokerName);
broker.start();
}
If no keystore is configured explicitly in the API, the micro broker will
use the keystore provided by the Lotus Expeditor platform:
if (!factory.exists(brokerName)) {
BrokerDefinition brokerDef= factory.createBrokerDefinition(brokerName);
brokerDef.setDataDirectory( dataDirectory );
brokerDef.setDefaultListenerSecure(true);
LocalBroker broker = factory.create(brokerDef);
broker.start();
} else {
LocalBroker broker = factory.getByName(brokerName);
broker.start();
}
It is also possible to define broker-wide
SSL settings when a broker is created and they can be used any time a SSL
listener or pipe is created afterwards. The following sample code creates
a broker with a default non-secure listener and defines broker-wide SSL
settings:
BrokerFactory factory = BrokerFactory.INSTANCE;
String brokerName = "FirstBroker";
String dataDirectory = ("path_to_broker_data_directory");
if (!factory.exists(brokerName)) {
BrokerDefinition brokerDef= factory.createBrokerDefinition(brokerName);
brokerDef.setDataDirectory( dataDirectory );
ServerSSLDefinition sslDef = brokerDef.createSSLDefinition();
sslDef.setKeyStore("path_to_keystore");
sslDef.setKeyStorePassword("123456".toCharArray());
sslDef.setTrustStore("path_to_truststore");
sslDef.setTrustStorePassword("123456".toCharArray());
LocalBroker broker = factory.create(brokerDef);
broker.start();
} else {
LocalBroker broker = factory.getByName(brokerName);
broker.start();
}
The micro broker will start up listening on the default non-secure port
number 1883. Now a SSL listener could be added by either using specific
SSL settings or broker-wide settings:
- Using listener-specific SSL settings
Communications comms = broker.getCommunications();
MQTTTCPListenerDefinition listDef = comms.createMQTTTCPListenerDefinition(8884);
ServerSSLDefinition sslDef = listDef.createSSLDefinition();
sslDef.setKeyStore("path_to_listener_keystore");
sslDef.setKeyStorePassword("123456".toCharArray());
listDef.setSSLDefinition(sslDef);
listDef.setSecure(true);
MQTTTCPListener list = comms.addTCPListener(listDef);
list.start();
- Broker-wide SSL settings
Communications comms = broker.getCommunications();
MQTTTCPListenerDefinition listDef = comms.createMQTTTCPListenerDefinition(8884);
listDef.setSecure(true);
MQTTTCPListener list = comms.addTCPListener(listDef);
list.start();
Bridge pipes: MQTT and WebSphere MQ connector
The code below shows how to create a SSL connector for a MQTT (either V3
or V5) bridge pipe and therefore connect securely to a remote end supporting
MQTT protocol:
- Uusing pipe-specific SSL settings
Obtain a handle to the broker's bridge
Bridge bridge = broker.getBridge();
Create a pipe definition -- this is the root of all bridge links
PipeDefinition pipe = bridge.createPipeDefinition("samplePipe");
Create the connector for the pipe
MQTTConnectionDefinition connector = bridge.createMQTTConnectionDefinition("samplePipeConnector");
MQTT: Set the specifics of the endpoint
connector.setHost("localhost");
connector.setPort(8883);
SSLDefinition sslDef = connector.createSSLDefinition();
sslDef.setTrustStore("path_to_pipe_truststore");
sslDef.setTrustStorePassword("123456".toCharArray());
connector.setSSLDefinition(sslDef);
connector.setSecure(true);
Attach the connector to the pipe
pipe.setConnection(connector);
…
- Using broker-wide SSL settings
Obtain a handle to the broker's bridge
Bridge bridge = broker.getBridge();
Create a pipe definition -- this is the root of all bridge links
PipeDefinition pipe = bridge.createPipeDefinition("samplePipe");
Create the connector for the pipe
MQTTConnectionDefinition connector = bridge.createMQTTConnectionDefinition("samplePipeConnector");
MQTT: Set the specifics of the endpoint
connector.setHost("localhost");
connector.setPort(8883);
connector.setSecure(true);
Attach the connector to the pipe
pipe.setConnection(connector);
…
For a bridge connection to WebSphere MQ, let’s assume that a secure
channel has been set up in the remote MQ server. A cipher suite must be
specified in the SSLDefinition attached to the bridge connector and must
be equivalent to the CipherSpec configured in the MQ server. Micro broker’s
MQ pipes set FIPS flag to false. Please refer to the
IBM
WebSphere MQ InfoCenter for
further details about CipherSpec and FIPS support.
Obtain a handle to the broker's bridge
Bridge bridge = broker.getBridge();
Create a pipe definition -- this is the root of all bridge links
PipeDefinition pipe = bridge.createPipeDefinition("samplePipe");
Create the connector for the pipe
MQJMSConnectionDefinition connector = bridge.createMQJMSConnectionDefinition("samplePipeConnector");
connector.setHost("MQ_server_address");
connector.setPort(1414);
connector.setChannel("SECURE.CHANNEL");
connector.setQueueManager("queue_manager_name");
SSLDefinition sslDef = connector.createSSLDefinition();
sslDef.setTrustStore("path_to_MQ_pipe_truststore");
sslDef.setTrustStorePassword("123456".toCharArray());
sslDef.setEnabledCipherSuites(new String[] {"SSL_RSA_WITH_RC4_128_SHA"});
connector.setSSLDefinition(sslDef);
connector.setSecure(true);
Attach the connector to the pipe
pipe.setConnection(connector);
The sample above makes use of the MQJMS
bridge connection, and not the JNDI bridge connection, as the MQJMS connection
can use the MQ client APIs directly to configure SSL. It is feasible
to use the JNDI bridge connection, although the MQ client's SSL settings
need to be pre-configured in JNDI, as the micro broker will see the client
as a generic JMS client.
SSL configuration in the client applications
SSL can be configured for clients in one of several ways, which the client
will use in the following order:
- Supplying an SSLSocketFactory - applications can supply their
own SocketFactory with the appropriate SSL settings. Only supported by
MQTT V5 client in Lotus Expeditor 6.2.
- Properties object - applications can supply a Properties object
containing the SSL settings.
- Lotus® Expeditor settings - if an Expeditor platform key store
is available, it will be used.
- Use JVM settings - There are a number of standard Java™ system
properties that can be used to configure key and trust stores.
If sslClientProps is a Java Properties object containing the SSL
settings for a particular application, the API for the different clients
look like:
MQTTv3 : properties.setSSLProperties(sslClientProps);
properties is a MqttProperties object
JMS client: ((JmsConnectionFactory) cf).setObjectProperty(MQTTConstants.MQTT_SSL_PROPERTIES,
sslClientProps);
MQTTv5: options.setSSLProperties(sslClientProps);
options is a MqttConnectOptions object
For instance, in a server authentication
scenario, the content of the sslClientProps object could be:
com.ibm.ssl.trustStore=path_to_truststore
com.ibm.ssl.trustStorePassword=123456
And the truststore will contain the certificate of the micro broker, so
that the identity of the micro broker can be verified by the client during
the SSL handshake.
Table
of Contents |
Previous
|
Next