IBM Support

Troubleshooting IBM MQ TLS Channels

Question & Answer


Question

Your IBM MQ system is having problems with TLS (formerly SSL) channels and you need to know how to troubleshoot the problem. This document describes how to access MQ TLS keystores and examine certificates in order to solve communications problems.

Answer

IBM MQ 8.0 and later for Linux, UNIX, AIX and Windows

IBM MQ 8.0 and later ship a private copy of GSKit specifically for use by the MQ installation.
Since GSKit is now packaged as part of MQ, displaying the MQ version also provides the GSKit version in use. The following command can be used to check the MQ and GSKit Version:

dspmqver -a

Rather than running native GSKit commands directly, use the MQ commands to use the iKeyman graphical interface or command line tools.

  • runmqakm     Runs the command line interface with FIPS. Does not support Java .jks keystore format.
  • runmqckm     Runs the command line interface without FIPS Support. Supports Java .jks keystore format.
  • strmqikm     Starts the iKeyman graphical interface
For FIPS Support see:

           Back to top

Troubleshooting TLS Channels

Use the errors in the server Queue Manager and the Cient application, and refer to the troubleshooting guide:
For more information about certificates, and how to manage them refer to the following documents:
https://www.ibm.com/support/pages/node/6445805
IBM MQ Personal and CA Certificates Explained And How To Identify Them
IBM MQ Certificate Authority Chain Information
https://www.ibm.com/support/pages/node/6382940
How to perform common tasks for the management of IBM MQ certificates
If the errors still occur after investigation based on the troubleshooting guides, gather simultaneous traces from the MQ Server and MQ Client or other MQ Server.
More information about this process can be read about here:
           Back to top

Certificate Troubleshooting Guides for IBM i:​​​​​​

IBM i Command Line
Display Message Queue Manager

 SSL:
   SSL CRL Namelist . . . . . . :

   SSL Key Repository . . . . . :   /QIBM/UserData/mqm/qmgrs/QMB/ssl/Keys

 

Alternatively, you can use runmqsc to display the SSLKEYR attribute of the queue manager:

https://www.ibm.com/support/pages/node/709275
Saving IBM MQ MQSC output
 

IBM i Command Line

===> RUNMQSC QMB


===> DISPLAY QMGR SSLKEYR
       1 : DISPLAY QMGR SSLKEYR
  AMQ8408: Display Queue Manager details.
     QMNAME(QMB)
     SSLKEYR(/QIBM/UserData/mqm/qmgrs/QMB/ssl/Keys)
 

Your queue manager can use the *SYSTEM key repository, which is held in /QIBM/UserData/ICSS/CertServer/DEFAULT.KDB.
Otherwise, the actual key repository file is the TLS Key Repository (SSLKEYR) value with a .KDB extension on it. You can also see other files in the same directory, such as a .RDB file for certificate requests and an .STH password stash file.

===> DSPMQM MQMNAME('QMB')

For IBM MQ client applications, check the MQSSLKEYR variable in the environment where the client runs:

IBM i Command Line

===> WRKENVVAR

IBM i Qshell

===> echo $MQSSLKEYR

Make sure that the directories in the key repository path are accessible to IBM MQ. The key repository files should also be accessible to IBM MQ, but secured against unwanted access by other users. Do not change the permissions on the *SYSTEM key repository!

 

IBM i Qshell

===> ls -ld /QIBM /QIBM/UserData /QIBM/UserData/mqm /QIBM/UserData/mqm/qmgrs /QIBM/UserData/mqm/qmgrs/QMB /QIBM/UserData/mqm/qmgrs/QMB/ssl

drwxr-sr-x   7 QSYS  0          8192 Feb 11 14:10 /QIBM
drwxr-sr-x  18 QSYS  0         24576 Feb 19 03:40 /QIBM/UserData
drwxrwsr-x   9 QMQM  QMQMADM    8192 Apr  9 11:31 /QIBM/UserData/mqm
drwxrwsr-x  18 QMQM  QMQMADM   24576 Apr  9 11:31 /QIBM/UserData/mqm/qmgrs
drwxrwsr-x  32 QMQM  QMQMADM   24576 Apr 11 09:04 /QIBM/UserData/mqm/qmgrs/QMB
drwxrws---   2 QMQM  QMQMADM    8192 Apr 18 16:53 /QIBM/UserData/mqm/qmgrs/QMB/ssl

===> ls -l /QIBM/UserData/mqm/qmgrs/QMB/ssl


total: 112 kilobytes
-rw-------   1 QMQM  QMQMADM   80080 Apr 18 16:16 Keys.KDB
-rw-------   1 QMQM  QMQMADM      80 Apr 18 16:16 Keys.RDB
-rw-------   1 QMQM  QMQMADM     129 Apr 18 16:16 Keys.STH
 
Access the IBM i Digital Certificate Manager (DCM) on your system:
https://www.ibm.com/docs/en/ibm-mq/9.3?topic=mq-digital-certificate-manager-dcm
IBM MQ / 9.3
Digital Certificate Manager (DCM)

Then click on the "Select a Certificate Store" button. Either choose the *SYSTEM store or enter the full path to your key repository (with .KDB extension), and its password, which was set by the administrator who created the repository. After clicking the "Continue" button you can use the "Manage Certificate" links to view certificates, check for expiring certificates, validate certificates, and other tasks:
 



IBM MQ has specific requirements for certificate label names. The label for a queue manager's personal certificate must be "ibmwebspheremq" followed by the queue manager name in lower case, while the personal certificate for a client must be "ibmwebspheremq" followed by the client userid in lower case.

Back to top

++ Additional Information:
tags: "MQ SSL"; "MQ TLS"; MQSSL; MQTLS

+++ end +++

[{"Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSYHRD","label":"IBM MQ"},"ARM Category":[{"code":"a8m0z00000008JwAAI","label":"Security-\u003ETLS (SSL)"}],"ARM Case Number":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"All Version(s)"}]

Product Synonym

WebSphere MQ WMQ

Document Information

Modified date:
30 October 2023

UID

swg21652675

Page Feedback