Service Virtualization


04-06-2016 06:21 PM

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

Cipher SpecCipher SuiteSSL version


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* 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: PKIX path building failed
Caused by: PKIX path building failed
Caused by: 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: 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: 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/  If you are not on Windows then you will need to find your JRE directory and find JRE_HOME/lib/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:


Try putting this line in


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 and earlier (IBM JRE v6)

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


For IBM MQ 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/  It should contain some lines like this:


Add the following lines after those:


Note that you may have a different number of lines already present in your 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 MQJE001: Completion Code '2', Reason '2059'.


Caused by: 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.

0 Favorited
0 Files

Tags and Keywords


09-07-2018 12:25 PM

Support worked with Shiva and issue is resolved when the MQ JARs were moved from DevTest_Home/lib -->DevTest_Home/lib/shared folder.

08-22-2018 11:34 AM

Hi Kevin,




We had exactly the same requirement, I did followed the post and it helped me to successfully establish connection to the queue Manager. But the only Issue I'm seeing is when I try to deploy the virtual services with this MQ Configuration setting in the VSE , I'm getting below exception.


| Exception:
| Message: Error while creating consumer BA_ENTRIES_ENQ_V4: JMSWMQ2008: Failed to open MQ queue 'XXXXX.POC'.
| Trapped Exception: JMSWMQ2008: Failed to open MQ queue 'XXXXX.POC'.
| Trapped Message: JMSWMQ2008: Failed to open MQ queue 'XXXXX.POC'.
JMS attempted to perform an MQOPEN, but WebSphere MQ reported an error.
Use the linked exception to determine the cause of this error. Check that the specified queue and queue manager are defined correctly.


Caused by: JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') reason '2085' ('MQRC_UNKNOWN_OBJECT_NAME').
... 44 more


However, When I publish a msg with the same MQ configuration onto XXXXX.POC queue from the workstation, I could able to see the msg coming in the queue. I'm not really sure why the deployed virtual services unable to connect to the queue where as the workstation is able to publish the msg.


I'm using CA DevTest 10.2 . I have provided the host,port,channel,QM,SSL Cipher Suite (TLS_RSA_WITH_AES_128_CBC_SHA256) and in the SSL context, under the trust store , I have made Devtest to trust all and in the keystore I have provided the client cert.


Any help is much appreciated.



09-14-2017 01:02 PM

If you run into the MQRC_UNSUPPORTED_CIPHER_SUITE error, here is a complementary document to help troubleshoot that.


04-11-2016 04:41 PM

For anyone curious, the problem here turned out to be using an old version of the MQ client jars against MQ 8.0.  I have updated the document accordingly.

04-09-2016 12:25 PM

Contact support and we'll try and figure it out together.

04-09-2016 09:45 AM

Hi Kevin,

I have tried the following

1. i have added IBM JRE  jar files to sun jre (but not from MQ folder instead downloaded JRE 7.1) i am able to see IBM jsse2 option in dev test 9.

2. i have updated sun JRE to Unlimited jce

3. I have commented disable algorithm in java security file.

4. i have ran it on pure IBM JRE 7 with SR6 FP1.(This in on a AIX 6.1 server)

In all above cases with ssl fips required set to true or false, i have got 2400 and worst part MQMD object is not at all initiated. But when I use (SSL_RSA_WITH_AES_128_CBC_SHA) with ssl debug on, i can atleast see some ssl packets interaction with mq server and throwing 2393 error. I am able to connect successfully with  SSL_RSA_WITH_3DES_EDE_CBC_SHA, MQ spec TRIPLE_DES_SHA_US(this is deprecated on latest MQ Versions) and when i upgrade my client jars in {{lisa_home}}/lib folder to MQ V8 then with SSL_RSA_WITH_3DES_EDE_CBC_SHA, MQ spec TLS_RSA_WITH_3DES_EDE_CBC_SHA but not with SSL_RSA_WITH_AES_128_CBC_SHA256. i have tried on LISA 7.5.2 and Dev test 9.1 but no luck. MQ is running on 7.5 and 8.Last option in hand is to add property to jvm arguments and try with TLS_RSA_WITH_AES_128_CBC_SHA256. But i don't have hope on it.

04-09-2016 04:22 AM

Looks like that's one that requires the IBM JRE (section 4.6). 

04-09-2016 02:19 AM

Hi Kevin, I am using SSL_RSA_WITH_AES_128_CBC_SHA256 cipher suite but i am getting mqrc 2400 error. It's there in 1.2 reference there any special requirements for this spec. I guess for AES 256 jce unlimited is required not for 128.

04-08-2016 04:54 PM

If anyone has a request for a messaging-related topic they'd like to see covered in detail then I'd be happy to see what I can do.

04-08-2016 04:07 PM

Keep these coming - Kevin.  I hope others in our Engineering team follow your path.

04-07-2016 04:03 PM

+1, good stuff

04-07-2016 03:56 PM

Great stuff, thanks Kevin.  Bookmarking this one.

04-07-2016 02:58 PM

Thanks for adding this, Kevin.  Very informative.

Related Entries and Links

No Related Resource entered.