Use SSL w/MQ

WebSphere MQ base Java client applications and WebSphere MQ JMS connections using TRANSPORT(CLIENT) support SSL encryption using a JSSE provider. J2SE v1.4 JVMs have a JSSE provider built in. Details of how to manage and store certificates can vary from provider to provider.

This section assumes that your JSSE provider is correctly installed and configured, and that suitable certificates have been installed and made available to your JSSE provider.

 

SSL administrative properties

SSL administrative properties include:

 

SSLCIPHERSUITE object property

To enable SSL encryption on a ConnectionFactory, use JMSAdmin to set the SSLCIPHERSUITE property to a CipherSuite supported by your JSSE provider. This must match the CipherSpec set on the target channel. However, CipherSuites are distinct from CipherSpecs and so have different names. Appendix H, SSL CipherSuites supported by WebSphere MQ contains a table mapping the CipherSpecs supported by WebSphere MQ to their equivalent CipherSuites as known to JSSE. Additionally, the named CipherSuite must be supported by your JSSE provider. book.

For example, to set a QueueConnectionFactory to connect to an SSL-enabled SVRCONN channel using a CipherSpec of RC4_MD5_EXPORT, issue the following command to JMSAdmin:

ALTER QCF(my.qcf) SSLCIPHERSUITE(SSL_RSA_EXPORT_WITH_RC4_40_MD5)

This can also be set from a program, using the setSSLCipherSuite() method on MQConnectionFactory.

For convenience, if a CipherSpec is specified on the SSLCIPHERSUITE property, JMSAdmin attempts to map the CipherSpec to an appropriate CipherSuite and issues a warning. This attempt to map is not made if the property is specified by a program.

 

SSLPEERNAME object property

A JMS application can ensure that it has connected to the correct queue manager, by specifying a distinguished name (DN) pattern. The connection succeeds only if the queue manager presents a DN that matches the pattern. For more details of the format of this pattern, refer to WebSphere MQ Security or the WebSphere MQ Script (MQSC) Command Reference.

The DN is set using the SSLPEERNAME property of ConnectionFactory. For example, the following JMSAdmin command sets the ConnectionFactory to expect the queue manager to identify itself with a Common Name beginning QMGR. with at least two Organizational Unit names, the first of which must be IBM and the second WEBSPHERE: 

ALTER QCF(my.qcf) SSLPEERNAME(CN=QMGR.*, OU=IBM, OU=WEBSPHERE)

Checking is case-insensitive, and semicolons can be used in place of the commas. This can also be set from a program, using the setSSLPeerName() method on MQConnectionFactory. If this property is not set, no checking is performed on the Distinguished Name supplied by the queue manager. This property is ignored if no CipherSuite is set.

 

SSLCERTSTORES object property

It is common to use a certificate revocation list (CRL) to manage revocation of certificates that have become untrusted. These are typically hosted on LDAP servers; JMS allows an LDAP server to be specified for CRL checking under Java 2 v1.4 or later. The following JMSAdmin example directs JMS to use a CRL hosted on an LDAP server named crl1.ibm.com: 

ALTER QCF(my.qcf) SSLCRL(ldap://crl1.ibm.com)

Note:
To use a CertStore successfully with a CRL hosted on an LDAP server, make sure that your Java Software Development Kit (SDK) is compatible with the CRL. Some SDKs require that the CRL conforms to RFC 2587, which defines a schema for LDAP v2. Most LDAP v3 servers use RFC 2256 instead.

If your LDAP server is not running on the default port of 389, the port can be specified by appending a colon and the port number to the host name. If the certificate presented by the queue manager is present in the CRL hosted on crl1.ibm.com, the connection does not complete. To avoid single-point-of-failure, JMS allows multiple LDAP servers to be supplied, by supplying a space-delimited list of LDAP servers. For example: 

ALTER QCF(my.qcf) SSLCRL(ldap://crl1.ibm.com ldap://crl2.ibm.com)

When multiple LDAP servers are specified, JMS tries each one in turn until it finds a server with which it can successfully verify the queue manager's certificate. Each server must contain identical information.

A string of this format can be supplied by a program on the MQConnectionFactory.setSSLCertStores() method. Alternatively, the application can create one or more java.security.cert.CertStore objects, place these in a suitable Collection object, and supply this Collection to the setSSLCertStores() method. In this way, the application can customize CRL checking. Refer to your JSSE documentation for details on constructing and using CertStore objects.

The certificate presented by the queue manager when a connection is being set up is validated as follows:

  1. The first CertStore object in the Collection identified by sslCertStores is used to identify a CRL server.

  2. An attempt is made to contact the CRL server.

  3. If the attempt is successful, the server is searched for a match for the certificate.

    1. If the certificate is found to be revoked, the search process is over and the connection request fails with reason code MQRC_SSL_CERTIFICATE_REVOKED.

    2. If the certificate is not found, the search process is over and the connection is allowed to proceed.

  4. If the attempt to contact the server is unsuccessful, the next CertStore object is used to identify a CRL server and the process repeats from step 2.

    If this was the last CertStore in the Collection, or if the Collection contains no CertStore objects, the search process has failed and the connection request fails with reason code MQRC_SSL_CERT_STORE_ERROR.

The Collection object determines the order in which CertStores are used.

If your application uses setSSLCertStores() to set a Collection of CertStore objects, the MQConnectionFactory can no longer be bound into a JNDI namespace. Attempting to do so causes an exception. If the sslCertStores property is not set, no revocation checking is performed on the certificate provided by the queue manager. This property is ignored if no CipherSuite is set.

 

SSLSocketFactory object property

You might want to customize other aspects of the SSL connection for an application. For example, you might want to initialize cryptographic hardware or change the KeyStore and TrustStore in use. To do this, the application must first create a javax.net.ssl.SSLSocketFactory instance customized accordingly. Refer to your JSSE documentation for information on how to do this, as the customizable features vary from provider to provider. Once a suitable SSLSocketFactory has been obtained, use the MQConnectionFactory.setSSLSocketFactory() method to configure JMS to use the customized SSLSocketFactory.

If your application uses setSSLSocketFactory() to set a customized SSLSocketFactory, the MQConnectionFactory can no longer be bound into a JNDI namespace. Attempting to do so causes an exception. If this property is not set, the default SSLSocketFactory is used; refer to your JSSE documentation for details on the behavior of the default SSLSocketFactory. This property is ignored if no CipherSuite is set.

Important:
Do not assume that use of the SSL properties ensures security when the ConnectionFactory is retrieved from a JNDI namespace that is not itself secure. Specifically, the standard LDAP implementation of JNDI is not secure; an attacker can imitate the LDAP server, misleading a JMS application into connecting to the wrong server without noticing. With suitable security arrangements in place, other implementations of JNDI (such as the fscontext implementation) are secure.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.