Configuring SSL for the IBM MQ connection (DataStage)

You can configure the IBM MQ connection to use SSL to securely connect to the target MQ queue.

This configuration uses an mqclient.ini configuration file that you place in persistent storage. You then reference the configuration file with an environment variable from the DataStage flow.

Obtain the CCDT file and the MQ server certificate
Prepare the keys database on the MQ client
Verify whether the server uses one-way or two-way authentication
Set up two-way authentication (if required)
Confirm the certificates are in the keys database
Place the files in Cloud Pak for Data persistent storage
Configure the environment variable for the DataStage flow

Obtain the CCDT file and the MQ server certificate

Obtain the following files from the MQ administrator:

MQ client channel definition file (CCDT). This is a binary file that defines the MQ connection details. Example name: AMQCLCHL.TAB
MQ server certificate that you add to the MQ Client keys database for secure MQ server authentication. Example name: mqservercert.arm

Prepare the keys database on the MQ client

The keys stash and database store the private and server certificates.

Create a /temp directory to create the files in.
Change to the /temp directory.

Create the keys database and stash for the keys and certificates:

/opt/mqm/bin/runmqckm -keydb -create -db mqkeysdb.kdb -type cms -pw <password> -stash

Add the mqservercert.arm server certificate:

/opt/mqm/bin/runmqckm -cert -add -db ./mqkeysdb.kdb -pw <password> -label ibmwebspheremq<QUEUE_MANAGER_NAME> -file mqservercert.arm

Verify whether the server uses one-way or two-way authentication

Run the following commands to determine whether one-way or two-way authentication is used by the MQ server:

# /opt/mqm/bin/runmqsc <QUEUE_MANAGER_NAME>
DISPLAY CHANNEL(<channelName>)

Check the output:

If the output contains SSLCAUTH(OPTIONAL), it means that one-way authentication is used. You can skip to Confirm the certificates are in the keys database.
If the output contains SSLCAUTH(REQUIRED), it means that two-way authentication is used. Proceed to Set up two-way authentication

Set up two-way authentication (if required)

Set up two-way authentication if you verified that the server uses two-way authentication.

Note: This two-way authentication configuration uses the default setup where an application connects to the queue manager with a personal certificate in the client keystore with a certificate that includes the label name ibmwebspheremquserid. For other connection methods, see the information about the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable in IBM MQ environment variables.

When the server uses two-way authentication, the MQ client uses the mqservercert.arm server certificate to validate the server. At the same time, a client certificate must be imported into the MQ server keys database so that the server can validate the client.

Generate a private client self-signed certificate:

/opt/mqm/bin/runmqckm -cert -create -db mqkeysdb.kdb -pw <password> -label ibmwebspheremq<USER_WHO_OWNS_RUNNING_PROCESS> -dn "CN=dsadm" -size 2048

Export the certificate to the arm file so it can be imported later into MQ server keys database:

/opt/mqm/bin/runmqckm -cert -extract -db mqkeysdb.kdb -pw <password> -label ibmwebspheremq<USER_WHO_OWNS_RUNNING_PROCESS> -target dsadm-mqclientcert.arm

Import the dsadm-mqclientcert.arm client certificate to the MQ server.

Run the following commands to reload the security settings:

# /opt/mqm/bin/runmqsc <managerName>
REFRESH SECURITY TYPE(SSL)

Confirm the certificates are in the keys database

Run this command to confirm that the certificates are in the keys database:

/opt/mqm/bin/runmqakm -cert -list -db mqkeysdb.kdb -pw <password>

One-way authentication

Sample output for one-way authentication shows that the MQ server certificate is categorized as 'trusted':

Certificates found
* default, - personal, ! trusted, # secret key
!       ibmwebspheremqMQMGRSSL

Two-way authentication

Sample output for two-way authentication contains the 'personal' certificate that the MQ client will present to the server:

Certificates found
* default, - personal, ! trusted, # secret key
!       ibmwebspheremqMQMGRSSL
-       ibmwebspheremqdsadm

Place the files in Cloud Pak for Data persistent storage

Place the files that you created in the previous steps into Cloud Pak for Data persistent storage so that they can be accessed during the DataStage flow runtime:

Create a directory in persistent storage named /ds-storage/config/mq.
Copy the following files to the /ds-storage/config/mq directory:
- Keys database: mqkeysdb.kdb
- Client channel definition table file: AMQCLCHL.TAB

In the /ds-storage/config/mq directory, create an mqclient.ini file with the following content:

ClientExitPath:
  ExitsDefaultPath=/var/mqm/exits
  ExitsDefaultPath64=/var/mqm/exits64

CHANNELS:
  ChannelDefinitionDirectory=/ds-storage/config/mq
  ChannelDefinitionFile=AMQCLCHL.TAB
SSL:
  SSLKeyRepository=/ds-storage/config/mq/mqkeysdb

If needed, adjust file access permissions to the /ds-storage/config/mq directory so that the files can be read by the user who will run the DataStage flow. The default username is dsadm.

Configure the environment variable for the DataStage flow

Add the MQCLNTCF environment variable to the job and set its value to the path that points to the mqclient.ini file. For example:

MQCLNTCF=/ds-storage/config/mq/mqclient.ini

Important: Do not to set any other MQ environment variables (like MQSERVER, MQCHLLIB, or MQCHLTAB) in the job because they might conflict with the settings in the mqclient.ini file.

Learn more

Parent topic: IBM MQ connection