The other day, an end-user contacted me saying that their MQAdmin had recently implemented IBM MQ AMS (Advanced Message Security) to some of their queue managers and that the end-user was having issues getting MQ Visual Edit working with those particular queue managers.
Its too bad that the customer chose IBM MQ AMS over Capitalware’s MQ Message Encryption. Oh well, c’est la vie – you win some and you lose some. 🙂
IBM’s MQ Knowledge Center has a page called: Quick Start Guide for AMS with Java clients. It provides a great guide on how to get started with AMS and Java applications but the web page is missing some key items:
- It doesn’t say that you must use MQ JAR files from MQ v9.0 or higher for a non-IBM JRE. i.e. AdoptOpenJDK or Oracle JRE
- It doesn’t say which MQ JAR files are actually required. It assumes an install with MQ JAR files or redistribution MQ JAR files.
- It doesn’t say where to store the keystore.conf file but if you read the Windows/Unix AMS pages, those pages say to put it in the {user’s_home_directory}/.mqs/ directory
- It doesn’t say what to do/set if the keystore.conf is not in the default directory.
If you use an IBM JRE then you can ignore item # 1 but for non-IBM JREs, you will need to use the MQ JAR files from MQ v9.0 or higher.
I’ve mentioned this before, MQ Visual Edit is compiled and linked with Excelsior Jet. Excelsior Jet is a licensed user of Oracle JDK/JRE. Like any other compiler and linker, you have to explicitly select what libraries are required for compilation and linkage. Selecting all of the MQ JAR files just means that the final executable will be a bloated file. For a regular Java (non-JMS) application, I found that the following are the required MQ JAR files (to work with AMS):
- com.ibm.mq.jar
- com.ibm.mq.commonservices.jar
- com.ibm.mq.headers.jar
- com.ibm.mq.jmqi.jar
- com.ibm.mq.pcf.jar
- bcpkix-jdk15on.jar
- bcprov-jdk15on.jar
The MQ Java client library will look for a file called keystore.conf in the following directory: {user’s_home_directory}/.mqs/. As noted in the Quick Start Guide for AMS with Java clients page, the keystore.conf file must contain the JKS keywords and values. In section 4 on that page it says:
If you already have a keystore.conf file because you have followed the instructions in the Quick Start Guide (Windows or UNIX), you can edit the existing file to add these lines.
That means you can have a single keystore.conf file with both JKS and CMS keywords and values. Very handy.
Finally, what if you don’t have the keystore.conf file in the default directory, then you need to set the MQS_KEYSTORE_CONF JVM environment variable as follows:
java -DMQS_KEYSTORE_CONF=C:\abc\keystore.conf MyAppl
Ok, so now that I have laid the groundwork, back to my customer’s issue with MQ Visual Edit and AMS enabled queue manager.
The customer was using a release of MQ Visual Edit that was built against MQ v8.0 JAR files and their MQAdmin had given them 2 keystore.conf files: 1 with CMS keywords and values and the other with JKS keywords and values. The user had put them in a directory structure like C:\abc\AMS\cms\kdb\ and C:\abc\AMS\jks\
The first problem was that particular release of MQ Visual Edit won’t work with AMS. I created a build of MQ Visual Edit against MQ v9.1.3 JAR files for the customer.
The second problem was that they were not setting the JVM environment variable and when they did, they pointed it to the CMS keystore. I had them correctly set the MQS_KEYSTORE_CONF JVM environment variable and point it to the JKS keystore.
Originally, with the older release of MQ Visual Edit, they were getting Reason Code of 2035 (MQRC_NOT_AUTHORIZED) when connecting to a queue/queue manager with AMS configured. Once they installed the new release of MQ Visual Edit and correctly set the MQS_KEYSTORE_CONF JVM environment variable, now they were getting Reason Code of 2012 (MQRC_ENVIRONMENT_ERROR). This made no sense. As far as I could tell, everything was correct by the documentation (and the parts that I had to read between the lines).
I had the end-user send me the MQ Visual Edit log file so that I could review everything that was going on.
- Using the latest release of MQ Visual Edit – check
- MQ Visual Edit was built with MQ v9.1.3 JAR files – check
- MQS_KEYSTORE_CONF JVM environment variable was set – check
- Path to keystore.con file was correct and it contained JKS keyword and values – check
I started to bang my head against the wall because the environment was set up correctly and I don’t know why MQ was returning a reason code of 2012 (MQRC_ENVIRONMENT_ERROR).
As I was looking over the MQ Visual Edit log file, I noticed that the end-user had 2 UserIds that were very close in spelling: roger vs rogerl. I told the customer to use the other UserId which happens to be their Windows UserId then everything worked. Hurray!!! 🙂
What I don’t understand is why MQ returned RC of 2012 for an incorrect/invalid UserId. It had me looking at the wrong area. My thinking is that MQ should have returned an RC of 2035 or 2063.
Regards,
Roger Lacroix
Capitalware Inc.
