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':

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

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:

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:

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

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

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

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:

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':

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:

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':

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':

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:

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:

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':

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

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:

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:

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

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.