IBM MQ and SSL/TLS

Document created by Kevin.Bowman Employee on Apr 6, 2016Last modified by Kevin.Bowman Employee on Dec 5, 2016
Version 5Show Document
  • View in full screen mode

After receiving a lot of questions about IBM MQ and SSL lately, I've decided to port over an old document I wrote on this topic and update it for the new IBM MQ Native step/VSE protocol.

 

This is written for DevTest 9.1.  It should mostly apply to DevTest 8.1 or later, when the IBM MQ Native step and VSE protocol was added.  However, some of the more esoteric SSL features mentioned were not added until later DevTest versions.

 

If you are using the old MQ step or VSE protocol then much of this can still apply to you.  However, you will only be able to configure SSL trust stores and key stores through the javax.net.ssl.* global system properties.

 

0. Client jar files

The very first step is to make sure you have the correct version of the MQ client jars.  They should match your MQ server version.  In many cases MQ servers and client jars are somewhat backwards and forwards compatible, but not when SSL is involved.

 

1. Cipher Specs and Cipher Suites

 

The first thing that separates the IBM MQ client's SSL support from most other clients is the fact that it needs to know the name of the Cipher Suite up front.  In many cases this is going to be the most difficult piece of information to acquire.

 

1.1. Finding the Cipher Spec

 

The first thing you will need is the name of the Cipher Spec that the MQ Server is configured with.  Note that this is different from a Cipher Suite.

 

You can get this information through MQ Explorer.  Navigate to your Queue Manager -> Advanced -> Channels.  Find the correct Server-Connection channel; it's typically called 'SYSTEM.DEF.SVRCONN'.  Right click on that row and select 'Properties':

cipher-spec-1.png

 

Click on the 'SSL' item on the left and find the 'SSL CipherSpec' field.  This is your Cipher Spec:

cipher-spec-2.png

 

1.2. Entering the Cipher Suite

 

Cipher Specs and Cipher Suites have different names, but there is a mostly 1-1 correspondence between them.  There are a number of documentation resources provided by IBM for mapping Cipher Specs to Cipher Suites.  Here are two links, one for IBM MQ 7.5 and one for IBM MQ 8.0.

 

Their internal documentation tends to move around, so if those links are broken then a Google search for 'ibm mq cipher suite' should be good enough to get started.

 

If all else fails, I have provided a combined table here, current as of April 2016:

Cipher SpecCipher SuiteSSL version
DES_SHA_EXPORTSSL_RSA_WITH_DES_CBC_SHASSL v1-2
DES_SHA_EXPORT1024SSL_RSA_EXPORT1024_WITH_DES_CBC_SHASSL v1-2
ECDHE_ECDSA_3DES_EDE_CBC_SHA256SSL_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHATLSv1.2
ECDHE_ECDSA_AES_128_CBC_SHA256SSL_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256TLSv1.2
ECDHE_ECDSA_AES_128_GCM_SHA256SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256TLSv1.2
ECDHE_ECDSA_AES_256_CBC_SHA384SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384TLSv1.2
ECDHE_ECDSA_AES_256_GCM_SHA384SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384TLSv1.2
ECDHE_ECDSA_NULL_SHA256SSL_ECDHE_ECDSA_WITH_NULL_SHATLSv1.2
ECDHE_ECDSA_RC4_128_SHA256SSL_ECDHE_ECDSA_WITH_RC4_128_SHATLSv1.2
ECDHE_RSA_3DES_EDE_CBC_SHA256SSL_ECDHE_RSA_WITH_3DES_EDE_CBC_SHATLSv1.2
ECDHE_RSA_AES_128_CBC_SHA256SSL_ECDHE_RSA_WITH_AES_128_CBC_SHA256TLSv1.2
ECDHE_RSA_AES_128_GCM_SHA256SSL_ECDHE_RSA_WITH_AES_128_GCM_SHA256TLSv1.2
ECDHE_RSA_AES_256_CBC_SHA384SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA384TLSv1.2
ECDHE_RSA_AES_256_GCM_SHA384SSL_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLSv1.2
ECDHE_RSA_NULL_SHA256SSL_ECDHE_RSA_WITH_NULL_SHATLSv1.2
ECDHE_RSA_RC4_128_SHA256SSL_ECDHE_RSA_WITH_RC4_128_SHATLSv1.2
FIPS_WITH_3DES_EDE_CBC_SHASSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHASSLv3
FIPS_WITH_DES_CBC_SHASSL_RSA_FIPS_WITH_DES_CBC_SHASSLv3
NULL_MD5SSL_RSA_WITH_NULL_MD5SSLv3
NULL_SHASSL_RSA_WITH_NULL_SHASSLv3
RC2_MD5_EXPORTSSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5SSL v1-2
RC4_56_SHA_EXPORT1024SSL_RSA_EXPORT1024_WITH_RC4_56_SHASSL v1-2
RC4_MD5_EXPORTSSL_RSA_EXPORT_WITH_RC4_40_MD5SSLv3
RC4_MD5_USSSL_RSA_WITH_RC4_128_MD5SSLv3
RC4_SHA_USSSL_RSA_WITH_RC4_128_SHASSL v1-2
TLS_RSA_WITH_3DES_EDE_CBC_SHASSL_RSA_WITH_3DES_EDE_CBC_SHATLSv1
TLS_RSA_WITH_AES_128_CBC_SHASSL_RSA_WITH_AES_128_CBC_SHATLSv1
TLS_RSA_WITH_AES_128_CBC_SHA256SSL_RSA_WITH_AES_128_CBC_SHA256TLSv1.2
TLS_RSA_WITH_AES_128_GCM_SHA256SSL_RSA_WITH_AES_128_GCM_SHA256TLSv1.2
TLS_RSA_WITH_AES_256_CBC_SHASSL_RSA_WITH_AES_256_CBC_SHATLSv1
TLS_RSA_WITH_AES_256_CBC_SHA256SSL_RSA_WITH_AES_256_CBC_SHA256TLSv1.2
TLS_RSA_WITH_AES_256_GCM_SHA384SSL_RSA_WITH_AES_256_GCM_SHA384TLSv1.2
TLS_RSA_WITH_DES_CBC_SHASSL_RSA_WITH_DES_CBC_SHATLSv1
TLS_RSA_WITH_NULL_SHA256SSL_RSA_WITH_NULL_SHA256TLSv1.2
TLS_RSA_WITH_RC4_128_SHA256SSL_RSA_WITH_RC4_128_SHATLSv1.2
TRIPLE_DES_SHA_USSSL_RSA_WITH_3DES_EDE_CBC_SHASSL v1-2

 

Once you have the right Cipher Suite for your MQ server's Cipher Spec, you can go into DevTest and configure your MQ Queue Manager Asset.

 

Make sure the 'PRO' button is enabled.  Click the '+' button towards the bottom right.  Select SSL -> SSL Cipher Suite:

qm-cipher-1.png

 

This will add a new field to the MQ Queue Manager asset.  You can select your cipher suite from a list:

qm-cipher-2.png

 

Or, if you'd rather just paste the cipher suite in, click the gear button on the right and select 'Direct Editor':

qm-cipher-3.png

 

Now you can paste the name of the Cipher Suite directly into the field:

qm-cipher-4.png

 

2. SSL Context

 

With the old MQ step you were required to configure things like key stores and trust stores using Java's global SSL properties.  With the new IBM MQ Native step and VSE protocol you can encapsulate that SSL configuration in your project config.  Each test or service can use its own SSL configuration, separate from everything else.  You can still use the javax.net.ssl.* global properties if you want, but that's not the recommended way going forward.

 

The first thing you need is an SSL Context asset.  This groups together all generic SSL-related configuration.  Open your Queue Manager asset, find the 'SSL Context' field, and click the '+' button to its right:

qm-ssl-1.png

 

2.1. Easy trust store

 

If you just need to do 1-way SSL, and don't care about verifying the server SSL certificate, then there is a short cut available.  Find the 'Trust Manager' field, click the '+' button to its right, and select 'Trust All Manager':

ssl-trust-all.png

 

This will create a trust manager that automatically allows any server SSL certificate.

 

If you just have 1-way SSL and don't care about explicitly verifying the server SSL certificate then you can stop here.  The SSL Context asset containing a 'Trust All Manager' asset should get you up and running.

 

2.2. Server certificate trust store

 

If you need to actually check the server's certificate then you will need a trust store containing the server SSL certificate exported from your MQ server.

 

2.2.1. Exporting to a trust store

 

Along with MQ Explorer, IBM provides a separate tool for managing SSL certificates and keys used by the MQ server, called 'IBM Key Management'.  This is the tool to use for exporting SSL certificates and keys from IBM MQ.

 

Open the IBM Key Management Tool.  Select 'Key Database File' -> 'Open'.  Click 'Browse' and find the location of your MQ server's key database file.  Typically, this is located at MQ_HOME/Qmgrs/<Queue Manager Name>/ssl/key.kdb.  You will likely need to know the password for the key database.  Once open, you should see at least one certificate in the key database:

ibm-key-man-1.png

 

If there is more than one then the one with an asterisk is the server certificate.  Typically it will be named 'ibmwebspheremq<queue manager name in lowercase>'.

 

Make sure the server certificate is selected and click 'Extract Certificate...' in the lower right.  For 'Data type' choose 'Binary DER data'.  For 'Certificate file name' enter 'server.der'.  Enter a directory to save the certificate file and click 'OK':

ibm-key-man-export-server.png

 

2.2.2. Adding a trust store to your project

 

Copy server.der to your DevTest install machine.  Open a command prompt and use the 'keytool' tool to import this certificate to a Java Key Store:

 

%DEVTEST_HOME%/jre/bin/keytool -import -keystore truststore.jks -file server.der -alias ibmwebspheremq<queue manager name in lowercase>        

 

(I'm not sure the -alias argument is necessary, but it won't hurt.)

 

Copy truststore.jks into your project, preferably under the Data/ directory.

 

Open your SSL Context asset.  Beside the 'Trust Manager' field click the '+' button.  Select 'Key Store File':

ssl-trust-store.png

 

Beside the 'File Name' field, use the 'Browse' button to find your trust store file.  Enter your password, and test the Asset to make sure it can successfully read your trust store file:

trust-test.png

 

With this trust store Asset selected for your SSL Context's Trust Manager it will verify the service's SSL certificate against the trust store file.

 

2.3. Client certificate key store

 

If you need to use Mutually Authenticated SSL with a client-side certificate then the process is similar to exporting the server certificate to a trust store, with a few extra steps.

 

2.3.1. Exporting to a key store

 

Open up your MQ server's key database in the Key Management Tool as before.  You should see a second certificate listed, one without an asterisk on it.  This is the client certificate.  If there are more than two certificates in the key database then you may need to ask your MQ admin which one is correct.

 

Make sure the client certificate is selected and click 'Extract Certificate...' in the lower right.  For 'Data type' choose 'Binary DER data'.  For 'Certificate file name' enter 'client.der'.  Enter a directory to save the certificate file and click 'OK'.

 

We need one more thing, and that's the client private key.  For this we have to create a key store for the IBM Key Management tool to export the key into.  On your DevTest install machine use the following commands to create an empty key store file:

 

%DEVTEST_HOME%/jre/bin/keytool -genkey -alias temp -keystore keystore.jks      
%DEVTEST_HOME%/jre/bin/keytool -delete -alias temp -keystore keystore.jks

 

Copy keystore.jks to your MQ server and go back to the IBM Key Management tool.  Make sure the client certificate is highlighted and click the 'Import/Export...' button on the right.

 

Under "Choose Action Type" choose "Export Key", Under "key file type" choose "JKS", and enter the file name and location of your blank key store.  Click "OK", and enter the key store password:

ibm-key-man-export-client.png

 

2.3.2. Adding a key store to your project

 

Copy client.der and keystore.jks to your DevTest install machine.

 

Open a command prompt and use the 'keytool' command to import the client.der certificate to a Java Key Store.

 

%DEVTEST_HOME%/jre/bin/keytool -import -keystore truststore.jks -file client.der -alias ibmwebspheremq<user name>        

 

(Again, I'm not sure the -alias argument is necessary, but it won't hurt.)

 

Note that if you are using a server side certificate as well then this should be the same file, so that both the client and server certificates end up in the same trust store file.

 

Copy truststore.jks and keystore.jks into your project, preferably under the Data/ directory.

 

If you haven't already done so, follow the above steps under 2.2.2 to create a Key Store Asset, pointing to your trust store, for the SSL Context's Trust Manager.

 

In most cases, configuring the client private key is very similar to adding a trust store.  Beside the 'Key Manager' field click the '+' button.  Select 'Key Store'.  Beside the 'File Name' field, use the 'Browse' button to find your key store file.  Enter your password, and test the Asset to make sure it can successfully read your key store file.

 

This should generally work if your key store just contains a single private key and the key password is the same as the key store password.  If either of those conditions are not met then you have to use a Key Manager.

 

2.3.3. Adding a key manager to your project

 

Open your SSL Context.  Beside the 'Key Manager' field click the '+' button.  Select 'Key Manager':

ssl-key-man.png

 

For the 'Key Store' field, select your key store Asset or follow the above steps in 2.3.2 to create it.

key-man.png

 

You will have to enter the key password even if it is the same as the key store password.  If there are more than one key in your key store then use the 'Alias' field to specify the alias for the particular private key that should be used.

 

3. Testing your connection

 

Once you have your SSL Cipher Suite and SSL Context set up, test your MQ Queue Manager asset to make sure it can connect:

qm-test.png

 

It's at this point that you can start to troubleshoot errors.

 

4. Common errors

 

4.1. Authentication error

 

Completion Code 2 (MQCC_FAILED), Reason Code 2035 (MQRC_NOT_AUTHORIZED)

 

You need to enter the correct username and password.  You may have to add these fields to the MQ Queue Manager Asset with the '+' button, they are located at 'Basic' -> 'User ID' and 'Basic' -> 'Password'.

 

4.2. Unable to find valid certification path

 

Completion Code 2 (MQCC_FAILED), Reason Code 2397 (MQRC_JSSE_ERROR)
...
Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed
...
Caused by: sun.security.validator.ValidatorException: PKIX path building failed
...
Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

 

This usually turns out to be an untrusted SSL certificate that wasn't put into truststore.jks.

 

4.3. SSL peer shut down incorrectly

 

Completion Code 2 (MQCC_FAILED), Reason Code 2397 (MQRC_JSSE_ERROR)
...
Caused by: java.io.EOFException: SSL peer shut down incorrectly

 

This is usually a configuration error on the MQ side, or DevTest is using the wrong port.

 

4.4. Peer Name errors

 

Completion Code 2 (MQCC_FAILED), Reason Code 2398 (MQRC_SSL_PEER_NAME_MISMATCH)

 

Completion Code 2 (MQCC_FAILED), Reason Code 2399 (MQRC_SSL_PEER_NAME_ERROR)

 

I don't know how the Peer Name stuff works, but we do have a property for it under the '+' button: 'SSL' -> 'SSL Peer Name'.

 

4.5. Protocol is disabled

 

Completion Code 2 (MQCC_FAILED), Reason Code 2397 (MQRC_JSSE_ERROR)
...
Caused by: javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)

 

In most cases, you have selected a Cipher Suite from SSLv3 or earlier that has been disabled by default in newer versions of Java.

 

Find the file DEVTEST_HOME/jre/lib/security/java.security.  If you are not on Windows then you will need to find your JRE directory and find JRE_HOME/lib/security/java.security

 

Open the file and find a line that looks like this:

 

jdk.tls.disabledAlgorithms=SSLv3, DH keySize < 768

 

The easiest thing is simply comment out the line:

 

#jdk.tls.disabledAlgorithms=SSLv3, DH keySize < 768

 

Note that this change will have to be made on every VSE server and Simulator server that performs IBM MQ operations with that SSL Cipher Suite.

 

4.6. Unsupported Cipher Suite

 

Completion Code 2 (MQCC_FAILED), Reason Code 2400 (MQRC_UNSUPPORTED_CIPHER_SUITE)

 

Completion Code 2 (MQCC_FAILED), Reason Code 2393 (MQRC_SSL_INITIALIZATION_ERROR)

 

This could be a typo from manually entering the Cipher Suite name.

 

This can also indicate that DevTest is using the wrong version of the MQ client jars.  Double check your jar versions to be sure.

 

If you have one of the following versions or later of the MQ client jars then you may be able to work around this with a system property:

  • 7.0.1.13+
  • 7.1.0.7+
  • 7.5.0.5+
  • 8.0.0.2+

Try putting this line in local.properties:

com.ibm.mq.cfg.useIBMCipherMappings=False

 

If all else fails then this could be a real Cipher Suite that is legitimately not supported by the Oracle JRE.  Some of the Cipher Suites mentioned in the table above in section 1.2 fall into this category.

 

This is solvable, but it involves actually copying the IBM JRE's JSSE provider into your DevTest JRE.

 

4.6.1. Finding the IBM JSSE jars

 

First you need access to your IBM MQ installation.  Then you need to find the IBM JRE installation directory underneath your MQ installation.  This is typically at something like MQ_HOME/java/jre or MQ_HOME/java/jre64.  Under this directory you will need the following files, found under lib/ and lib/ext:

 

For IBM 7.5.0.2 and earlier (IBM JRE v6)

  • ibmjcefips.jar
  • ibmjcefw.jar
  • ibmjceprovider.jar
  • ibmjgssprovider.jar
  • ibmjsseprovider2.jar
  • ibmpkcs.jar

 

For IBM MQ 7.5.0.3 and later (IBM JRE v7):

  • ibmcertpathprovider.jar
  • ibmjcefips.jar
  • ibmjcefw.jar
  • ibmjceprovider.jar
  • ibmjgssprovider.jar
  • ibmjsseprovider2.jar
  • ibmpkcs.jar
  • ibmpkcs11impl.jar

 

4.6.2. Installing the IBM JSSE provider in the Oracle JRE

 

Now you need to find DevTest's Oracle JRE.  On Windows this is usually DEVTEST_HOME/jre.  On other OSs it will be wherever the system has installed Java.

 

Copy the above jar files to JRE_HOME/lib/ext.

 

Find the file JRE_HOME/lib/security/java.security.  It should contain some lines like this:

 

security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=sun.security.ec.SunEC
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=com.sun.security.sasl.Provider
security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.9=sun.security.smartcardio.SunPCSC
security.provider.10=apple.security.AppleProvider

 

Add the following lines after those:

 

security.provider.11=com.ibm.jsse2.IBMJSSEProvider2
security.provider.12=com.ibm.crypto.provider.IBMJCE
security.provider.13=com.ibm.security.jgss.IBMJGSSProvider
security.provider.14=com.ibm.security.cert.IBMCertPath
security.provider.15=com.ibm.security.sasl.IBMSASL

 

Note that you may have a different number of lines already present in your java.security file.  Make sure the numbering of the new lines continues where the existing lines left off.  You cannot skip or repeat numbers with the 'security.provider.N' property names.

 

Note that this change will have to be made on every VSE server and Simulator server that performs IBM MQ operations with that SSL Cipher Suite.

 

4.6.3. Configuring your SSL Context

 

Restart Workstation and make sure it starts up fine without any errors.

 

Open your SSL Context Asset.  Find the 'Provider' field.  Click the drop down and make sure you see some IBM entries in there:

ssl-ibm.png

 

Select 'IBMJSSE2'.  Click the test button to test the SSL Context out:

ssl-ibm-test.png

 

If you don't see an error at this stage then you have successfully installed the IBM JSSE provider.  You should be able to handle almost any wacky Cipher Suite that's thrown at you.

 

4.7. Channel Negotiation Failed

com.ibm.mq.MQException: MQJE001: Completion Code '2', Reason '2059'.

...

Caused by: com.ibm.mq.jmqi.JmqiException: CC=2;RC=2059;AMQ9503: Channel negotiation failed.

This usually happens when the MQ server requires a client-side certificate.  The client side (DevTest) is either missing the client-side certificate or is providing the incorrect one.  Make sure you have followed the instructions in section 2.3 to add a client-side key store to your SSL context.

4 people found this helpful

Attachments

    Outcomes