Configuring DataPower MQ client to use SSL in mutual authentication mode

Resolving The Problem

In order to use this technote, you should have a working knowledge of how to setup and administer MQ Server in Windows, AIX, Solaris, HP-UX, or Linux environment. You should also have an understanding of how to configure DataPower MQ Manager Object that connects to remote WebSphere MQ Queue Manager (qmgr). This technote focuses on configuring DataPower MQ Client to use SSL in mutual authentication mode with Firmware Releases 3.8.2 and later fixpacks. Follow these steps to configure DataPower MQ Manager Object (mq-qm object) to access WebSphere MQ Queue Manager (Remote MQ Server) in SSL mutual authentication mode.

WebSphere MQ configuration prerequisites

The following three steps are necessary to make sure that the SSL configurations for the Remote MQ Server is correctly working. Refer to IBM WebSphere MQ product manuals to configure MQ environment to work in SSL mutual authentication mode.

1. Configure WebSphere MQ Queue Manager (Remote MQ Server) to use SSL authentication (SSLCAUTH as "required") using URL: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/topic/com.ibm.mq.explorer.doc/e_ssl.htm.
2. Configure WebSphere MQ Client to use SSL authentication.
3. Verify that WebSphere MQ Client can PUT/GET message(s) using application programs such as amqsputc and amqsgetc with MQ Queue Manager in SSL mutual authentication mode.
   

1. Generate the self signed key/certificate pair using the "crypto tool" from the DataPower device.
2. Download the two files to your local machine. For the sake of illustration purpose, the names of the key and certificate files are defined as "dpmqclient-privkey.pem" and "dpmqclient-sscert.pem" respectively.
3. Assuming that openssl tool (www.openssl.org) is installed in the local machine. With openssl tool, you can use the following command to create a "pkcs12" type key from the above key/certificate pair which are of PEM type. This step is necessary as MQ key database will not import key/certificate files created as PEM.
   
   openssl pkcs12 -export -out dpmqclient-key.p12 -in dpmqclient-sscert.pem -inkey dpmqclient-privkey.pem -name ibmwebspheremqadmin
   
   Note the value associated with "-name" parameter. IBM WebSphereMQ client required a friendly label as "ibmwebspheremq<userid>" of the MQ client user. In this example, the user name is being used as "admin". This user must be used in the DataPower MQ Queue Manager object and it must also be an authorized user for both the DataPower MQ instance as well as for the remote WebSphere MQ Server. Please refer to Pages G58-62 in the 3.6.0-WebGui Guide for various fields as described in MQ Queue Manager configuration screen. Also note the following two fields with appropriate values which are required for the MQ Queue Manager object to connect the remote WebSphere MQ Server in SSL mode.

SSL Key Repository: The key database file name
SSL Cipher Specification: TRIPLE_DES_SHA_US

UNIX, you can use "gsk7cmd" to accomplish the key import task:

gsk7cmd -cert -import -file filename -pw password -type pkcs12 -target filename -target_pw password -target_type cms


Windows, you can use "runmqckm" command to accomplish the key import task:

runmqckm -cert -import -file filename -pw password -type pkcs12 -target filename -target_pw password -target_type cms

where:

-file filenam is the fully qualified file name of the file containing the PKCS12 certificate
-pw password is the password for the PKCS12 certificate
-type pkcs12 is the type of the file
-target filename is the name of the destination CMS key database
-target_pw password is the password for the CMS key database
-target_type cms is the type of the database specified by -target

1. Start the iKeyman GUI using either the gsk7ikm command (on UNIX) or the strmqikm command (on Windows).
2. From the Key Database File menu, click Open. The Open window displays.
3. Click Key database type and select CMS (Certificate Management System).
4. Click Browse to navigate to the directory that contains the key database files.
5. Select the key database file in which you want to save the certificate, for example key.kdb.
6. Click Open. The Password Prompt window displays.
7. Type the password you set when you created the key database and click OK.
8. The name of your key database file displays in the File Name field. The Personal Certificates menu will display both "ibmwebspheremq<qmgr>" and "ibmwebspheremq<user>" labels.
9. In the WebSphere MQ Certificate key database, there is one certificate assigned to the queue manager or client. The certificate's Friendly Name attribute contains the string ibmwebspheremq followed in lower case by the queue manager name or the client logon ID. This Friendly Name value becomes the label of the certificate in the GSKit key database. Refer to Alter the Friendly Name (Label) of pkcs12 certificates for importing into GSKit if you want to alter the Friendly Name (Label) of pkcs12 certificates that are part of WebSphere MQ Certificate key database. Refer to "Migrating SSL Security Certificates in WebSphere MQ for Windows" if you want to fix the migrated certificates from the WebSphere MQ V5.3 version to later version.
10. From the key database File menu, click Stash Password. This will create the new password file as "key.sth". Select OK and close the key database File.
11. Upload the "key.kdb" and "key.sth" files to "cert:" directory of the DataPower box. Configure the MQ client object in the DataPower box to use this key database as shown in the screen shot above to connect in SSL mutual authentication mode with the MQ Manager. The following screen shot shows the "key.kdb" and "key.sth" files are located in the "cert:" directory of the application domain. This screen shot below shows that mq-qm object is using the "key.kdb" file located in the "cert:" directory with the associated cipher specification as "TRIPLE_DES_SHA_US". Note that SSL Proxy Profile field is "(none)" as this configuration is using key repository method for SSL connection.
12. Refresh the SSL security attribute of the MQ Manager to use this key database and password files from the host machine running MQ Server.
    
    Runmqsc <MQ Manager>
    Refresh security type(ssl)
    End
    
13. Test your application to PUT/GET MQ message(s) using DataPower MQ client with the new configuration.