IBM Support

How do I configure an MQ client c-based application like amqsputc / amqsgetc to connect to an MQ server with SSL?

How To


Summary

How do I configure an MQ client c-based application like amqsputc to connect to an MQ server with SSL?

Please provide step-by-step instructions.

Environment

What version of MQ server are you using? (full version from dspmqver?)

What version of MQ client are you using?

There are several cipherspec changes between versions of MQ, so be sure to pick a compatible cipherspec when configuring this.

Setting up SSL is discussed in our infocenter, If you are not familiar with setting up SSL, keystores and certificate management on the MQ server you may want to contact our Services team for some training in this area.

I think the hard part is getting the keystores/certificates configured correctly.

You need to create keystores which contain certificates for the MQ server queue manager (key.kdb) and also for the user runningthe MQ client application (user.kdb).

These keystores must contain the necessary personal certificates and signer certificates. The personal certificates uniquely identify the queue manager or user, the signers are used to validate the certificates.

The signer's are exchanged between the queue manager and user keystores.

Once these are configured correctly on both sides, it is just a matter of pointing to them and setting a compatible cipher on both ends of the channel.

Below are step-by-step instructions using self-signed certificates.

This is also discussed in the infocenter here:

https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.1.0/com.ibm.mq.pro.doc/q014220_.htm

Steps

Here are full steps you should be able to cut/paste and this on your system to test.

Steps below:  To setup SSL between queue manager and C-program (amqsputc/amqsgetc)

PS: there are several ways this can be done.. here is one example:  

To setup SSL between queue manager and an MQ client application amqsputc/amqsgetc.  

 // On the MQ server, create a queue manager: .
crtmqm SSL1
strmqm SSL1
//in rummqsc runmqsc SSL1
// Define basic listener, channels, etc.
// in runmqsc
runmqsc SSL1
DEFINE LISTENER(LIST1) TRPTYPE(TCP) PORT(1490) CONTROL(QMGR)
START LISTENER(LIST1)
DEFINE CHANNEL(SSL1.SVRCONN) CHLTYPE(SVRCONN) SSLCAUTH(OPTIONAL)
DEFINE QLOCAL(Q1)
// This defines CLNTCONN, same name as SVRCONN, but info to go into
// CCDT (client channel definition table) for client to use to connect.
// The CCDT will be needed to specify SSL settings later.
// Make sure to specify the correct CONNAME for your qmgr (hostname or ipaddr and port for yours
DEFINE CHANNEL(SSL1.SVRCONN) CHLTYPE(CLNTCONN) CONNAME ('a.b.c.d(1490)') QMNAME(SSL1)
// if MQ v7.1 or higher, disable CHLAUTH and CONNAUTH (v8) to test
ALTER QMGR CHLAUTH(DISABLED) CONNAUTH (' ')
REFRESH SECURITY TYPE(CONNAUTH)
// note value of sslkeyr - full path, base file name of keystore for queue manager)
DISPLAY QMGR SSLKEYR
END
// Before continuing, you can test using amqsputc/amqsgetc without SSL.
// As we are connecting using the
// Copy the AMQCLCHL.TAB, client channel definition table(CCDT) to the a directory,
// in this case, C:\tmp directory, then set the needed environment variables so the
// MQ client will use this, make sure NOT to set the MQSERVER variable. http://www.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.con.doc/q016730_.htm?lang=en
// The CCDT is initially located in the @ipcc subdirectory
copy <MQ-datadirectory>\qmgrs\SSL1\@ipcc\amqclchl.tab c:\tmp
// 2 env vars needed for CCDT (ensure MQSERVER is NOT set)
set MQCHLLIB=C:\tmp
set MQCHLTAB=AMQCLCHL.TAB
// Then run the amqsputc/amqsgetc programs to ensure this works..
amqsputc Q1 SSL1
amqsgetc Q1 SSL1
// if any issues, resolve them before proceeding, check the MQ qmgr error logs
//----------------------
// Now to start the actual SSL stuff!
// setup queue manager ssl keystore repository and certificate
// goto <MQ-datadirectory>/qmgrs/<QMGR>/ssl directory:
cd <MQ-datadirectory>/qmgrs/<QMGR>/ssl
// create qmgr keystore
runmqckm -keydb -create -db key.kdb -type cms -pw passw0rd -stash
// create self-signed cert for queue manager
runmqckm -cert -create -db key.kdb -pw passw0rd -label ibmwebspheremqssl1 -dn "CN=ssl1,O=IBM,C=US" -size 2048
// extract public part to be used to exchange to the connecting user
runmqckm -cert -extract -db key.kdb -pw passw0rd -label ibmwebspheremqssl1 -target ssl1.arm
// note the new files created
// note that name of the keystore .. key.kdb (base filename = key)
// matches value above in qmgr SSLKEYR, viewed earlier
// also note the name of the queue manager certificate, it must be
// ibmwebspheremq followed by the name of the queue manager in all lower case,
// with MQ v8 it can be different
// but we still recommend following this convention, it is required in versions before MQ v8.
// For the client/user...
// setup user ssl repository and cert
// in some user dir: (I did this in c:\tmp)
cd c:\tmp
// create user keystore (must be .kdb (cms type) for c-based MQ client app.
// note: java programs use .jks (java keystores), whereas the .kdb (cms) is for other MQ client apps.
runmqckm -keydb -create -db user.kdb -type cms -pw passw0rd -stash
// create self-signed cert for the user, NOTE my user id is 'mcregge' so I am following
// required convention where label name must be ibmwebspheremq followed by the userid (all lower case)
// see step 9 in this knowledgecenter page
https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.sec.doc/q012770_.htm
runmqckm -cert -create -db user.kdb -pw passw0rd -label ibmwebspheremqmcregge -dn "CN=mcregge,O=IBM,C=US" -size 2048
// extract public part of this to exchange to the queue manager, so the queue manager can validate the user's cert.
runmqckm -cert -extract -db user.kdb -pw passw0rd -label ibmwebspheremqmcregge -target mcregge.arm
//-----------------------
// exchange signer cert information..(you may need to add paths to the .arm files, or keystores
// or copy the .arm file to the location of the keystore.
// add MQ qmgr server signer cert to user kdb keystore
// in the c:\tmp subdirectory
runmqckm -cert -add -db user.kdb -pw passw0rd -label ssl1_signer -file ssl1.arm
// add user certificate to the queue managers keystore db
// in qmgrs/<QMGR>/ssl directory:
runmqckm -cert -add -db key.kdb -pw passw0rd -label ibmwebspheremqmcregge -file mcregge.arm
// list the contents of the keystores to ensure each has the personal certificate and the needed signer certificate
runmqckm -cert -list personal -db user.kdb -pw passw0rd
runmqckm -cert -list ca -db user.kdb -pw passw0rd

//-------------------------------
// Ok getting close, just need to refresh the SSL/keystores and enable the ciphers
// Enable SSL on qmgr channel
// for this example, using... TLS_RSA_WITH_AES_128_CBC_SHA
runmqsc SSL1
// Update SVRCONN channel
ALTER CHANNEL(SSL1.SVRCONN) chltype(SVRCONN) sslciph(TLS_RSA_WITH_AES_128_CBC_SHA256)
// This updates the CLNTCONN and the CCDT file
ALTER CHANNEL(SSL1.SVRCONN) chltype(CLNTCONN) sslciph(TLS_RSA_WITH_AES_128_CBC_SHA256)
// Important to refresh security type (SSL) to read in the new keystore certificates
REFRESH SECURITY TYPE(SSL)
//--------------------------------
// Copy the updated AMQCLCHL.TAB, client channel definition table(CCDT) to the C:\tmp directory
copy <MQ-datadirectory>\qmgrs\SSL1\@ipcc\amqclchl.tab c:\tmp
// Ensure the needed environment variables are set.
set MQCHLLIB=C:\tmp
set MQCHLTAB=AMQCLCHL.TAB
// MQSSLKEYR is need so that the MQ client knows what keystore to use..
// note it is the full path, including the base file name but not the .kdb extension
// my keystore file is user.kdb in the C:\tmp subdirectory..
set MQSSLKEYR=C:\tmp\user
// Then run the amqsputc/amqsgetc programs to ensure this works..
 
amqsputc Q1 SSL
// Hopefully all works
// if errors, check the client and queue manager error logs.

Document Location

Worldwide

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSYHRD","label":"IBM MQ"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym

MQ

Document Information

Modified date:
11 February 2020

UID

ibm11088020