WebSphere MQ base Java client applications and WebSphere MQ JMS connections using TRANSPORT(CLIENT) support Secure Sockets Layer (SSL) encryption. SSL provides communication encryption, authentication, and message integrity. It is typically used to secure communications between any two peers on the Internet or within an intranet.
WebSphere MQ classes for Java uses Java Secure Socket Extension (JSSE) to handle SSL encryption, and so requires 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. For information about this, refer to your JSSE provider's documentation.
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.
If your WebSphere MQ JMS client application uses a client channel definition table to connect to a queue manager, see Using a client channel definition table.
This section introduces the SSL administrative properties, as follows:
To enable SSL encryption on a ConnectionFactory object, 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 D. SSL CipherSpecs and CipherSuites contains a table mapping the CipherSpecs supported by WebSphere(R) MQ to their equivalent CipherSuites as known to JSSE. Additionally, the named CipherSuite must be supported by your JSSE provider. For more information about CipherSpecs and CipherSuites with WebSphere MQ, see WebSphere MQ Security.
For example, to set up a ConnectionFactory object that can be used to create a connection over an SSL enabled MQI channel with a CipherSpec of RC4_MD5_EXPORT, issue the following command to JMSAdmin:
ALTER CF(my.cf) SSLCIPHERSUITE(SSL_RSA_EXPORT_WITH_RC4_40_MD5)
This can also be set from an application, using the setSSLCipherSuite() method on an MQConnectionFactory object.
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 an application.
If you require a connection to use a CipherSuite that is supported by the IBM Java JSSE FIPS provider (IBMJSSEFIPS), set the SSLFIPSREQUIRED property of the connection factory to YES. The default value of this property is NO, which means that a connection can use any CipherSuite that is not supported by IBMJSSEFIPS.
If an application uses more than one connection, the value of SSLFIPSREQUIRED that is used when the application creates the first connection determines the value that is used when the application creates any subsequent connection. This means that the value of the SSLFIPSREQUIRED property of the connection factory that is used to create a subsequent connection is ignored. You must restart the application if you want to use a different value of SSLFIPSREQUIRED.
An application can set this property by calling the setSSLFipsRequired() method of a ConnectionFactory object. The property is ignored if no CipherSuite is set.
A JMS application can ensure that it connects 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 a ConnectionFactory object. For example, the following JMSAdmin command sets a ConnectionFactory object to expect the queue manager to identify itself with a Common Name beginning with the characters QMGR., and with at least two Organizational Unit names, the first of which must be IBM and the second WEBSPHERE:
ALTER CF(my.cf) SSLPEERNAME(CN=QMGR.*, OU=IBM, OU=WEBSPHERE)
Checking is not case sensitive and semicolons can be used in place of commas. This can also be set from an application using the setSSLPeerName() method on an MQConnectionFactory object. 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.
It is common to use a certificate revocation list (CRL) to identify certificates that are no longer trusted. CRLs 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 CF(my.cf) SSLCRL(ldap://crl1.ibm.com)
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 a single point of failure, JMS allows multiple LDAP servers to be supplied by supplying a list of LDAP servers delimited by the space character. Here is an example:
ALTER CF(my.cf) 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 in this format can be supplied by an application 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 object 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:
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.
This property represents the total number of bytes sent and received by a connection before the secret key that is used for encryption is renegotiated. The number of bytes sent is the number before encryption, and the number of bytes received is the number after decryption. The number of bytes also includes control information sent and received by the WebSphere MQ JMS client.
For example, to configure a ConnectionFactory object that can be used to create a connection over an SSL enabled MQI channel whose secret key is renegotiated after 4 MB of data have flowed, issue the following command to JMSAdmin:
ALTER CF(my.cf) SSLRESETCOUNT(4194304)
An application can set this property by calling the setSSLResetCount() method of a ConnectionFactory object.
If the value of this property is zero, which is the default value, the secret key is never renegotiated. The property is ignored if no CipherSuite is set.
If you are using an HP or Sun Java 2 Software Development Kit (SDK) or Java Runtime Environment (JRE), do not set this property to a value other than zero. If you do set the property to a value other than zero, a connection fails when it attempts to renegotiate the secret key.
For more information about the secret key that is used for encryption on an SSL enabled channel, see WebSphere MQ Security.
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 object that is customized accordingly. Refer to your JSSE documentation for information on how to do this, as the customizable features vary from provider to provider. After a suitable SSLSocketFactory object is obtained, use the MQConnectionFactory.setSSLSocketFactory() method to configure JMS to use the customized SSLSocketFactory object.
If your application uses the setSSLSocketFactory() method to set a customized SSLSocketFactory object, the MQConnectionFactory object 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 object is used. Refer to your JSSE documentation for details on the behavior of the default SSLSocketFactory object. This property is ignored if no CipherSuite is set.
If you change the contents of the JSSE keystore or truststore, or change the location of the keystore or truststore file, WebSphere MQ JMS applications that are running at the time do not automatically pick up the changes. For the changes to take effect, the following actions must be performed:
After these actions have been performed, the applications can then recreate their connections.
Depending on how you design your applications, and on the function provided by your JSSE provider, it might be possible to perform these actions without stopping and restarting your applications. However, stopping and restarting the applications might be the simplest solution.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
jms11ssl |