TLS Configuration

IBM MQ moves payment files, health records, and inventory events across networks you do not fully control. TLS configuration is how you encrypt those bytes in flight and prove you reached the intended queue manager—not an impostor in the path. Administrators work with three related surfaces: the queue manager key repository (SSLKEYR), channel and listener attributes (SSLCIPH, SSLCAUTH), and—for modern estates—the mqweb HTTPS keystore used by REST and the console. Beginners often enable TLS on only one side of an SDR/RCVR pair or update a server cert without importing the new CA on clients, producing BINDING failures that look like network outages. This tutorial gives a ordered setup checklist for distributed queue managers, explains what each attribute changes, compares one-way and mutual TLS at configuration time, covers client trust stores and CCDT fields, and points to certificate validation and cipher selection as the next depth topics.

SSLKEYR and the Key Repository

ALTER QMGR SSLKEYR('/var/mqm/qmgrs/QM1/ssl/key') points the queue manager at a key database. On Linux you typically see key.kdb, key.sth, and key.rdb files managed with IBM GSKit or runmqakm commands documented for your release. The personal certificate is what partners see when they connect; the trusted CA certificates let MQ validate partner certs during mutual TLS. The repository is per queue manager—two QMs on one host have separate SSLKEYR paths. Backup these files before renewal; losing a private key requires reissuing certs to all partners.

1
2
3
4
5
6
7
8
ALTER QMGR SSLKEYR('/var/mqm/qmgrs/QM1/ssl/key')
* Create personal cert and sign with corporate CA — platform tools per IBM docs
* Label the cert for channel use (AMQ channel label is common default)
DEFINE LISTENER('TLS.LISTENER') TRPTYPE(TCP) PORT(1414) CONTROL(QMGR)
ALTER LISTENER('TLS.LISTENER') TRPTYPE(TCP) SSLCIPH('TLS_RSA_WITH_AES_256_GCM_SHA384')
START LISTENER('TLS.LISTENER')
DEFINE CHANNEL('APP.SVRCONN') CHLTYPE(SVRCONN) TRPTYPE(TCP) +
  SSLCIPH('TLS_RSA_WITH_AES_256_GCM_SHA384')

Cipher names must be valid for your MQ version and platform—replace the example with a spec from IBM supported cipher lists. A listener SSLCIPH applies to inbound TCP connections before the channel name is known; channel SSLCIPH further constrains negotiation for that channel instance.

Enabling TLS on Channel Pairs

For SDR/RCVR between two queue managers, set SSLCIPH on both definitions to compatible values, ensure both SSLKEYR repositories trust each other CAs, and start listeners on TLS ports. The sender CONNAME must include the TLS listener port. Sequence: establish lab TCP, add server cert only (one-way TLS), verify BINDING, then add SSLCAUTH(REQUIRED) on RCVR if mutual TLS is required, then CHLAUTH SSLPEERMAP. Skipping steps makes root-cause analysis harder.

Client TLS Configuration

MQI clients set SSL in MQCD connection descriptors or CCDT channel definitions: SSLCipherSpec, SSLPeerName, KeyRepository fields per client documentation. Java JMS uses similar properties on the connection factory. Node, Python, and Go clients inherit the C client behavior—wrong trust store path produces handshake failures before MQ reason codes. Import the queue manager issuing CA (or public cert) into the client trust store; for mutual TLS, supply the client personal cert and private key in the client key repository.

mqweb HTTPS Configuration

REST and console traffic to port 9443 uses Liberty ssl configuration in mqweb server.xml fragments—not the channel SSLKEYR unless you deliberately align them. Corporate policies may require the same CA chain for audit simplicity, but the files are maintained separately. When mqweb cert expires, channels may still run while REST fails—monitor both calendars.

Explainer: Envelope and Wax Seal

TLS is the tamper-evident envelope around your letter. SSLKEYR is the desk drawer where you keep your seals and stamps. SSLCIPH picks how strong the envelope material is. SSLCAUTH on the receiver means “show me your ID card too, not just my stamp on the reply envelope.”

Platform Notes

• Linux/Windows distributed: GSKit key.kdb, runmqakm, default paths under /var/mqm.
• z/OS: key rings in RACF; channel SSL parameters reference ring names.
• Containers: mount secrets as volumes; avoid baking private keys into image layers.
• Kubernetes: cert-manager or secrets for mqweb and QM TLS separately.

Hardening Defaults

IBM MQ 9.x installs trend toward stronger out-of-the-box TLS than legacy 7.x estates. Still review organizational cipher baselines (disable NULL, EXPORT, SSLv3, short keys). Align with payment card or healthcare standards if applicable. Document exception channels with expiry dates for weak cipher partners during migration.

Explain Like I'm Five: TLS Configuration

TLS configuration is teaching the mail truck to drive through a secret tunnel so nobody on the road can read the packages, and giving each post office a special stamp so fake offices cannot pretend to be yours.

Practice Exercises

Exercise 1

Write MQSC to set SSLKEYR and SSLCIPH on one SVRCONN and its listener port.

Exercise 2

List differences between rotating channel cert versus mqweb cert in a runbook.

Exercise 3

Partner connects but handshake fails—what three DISPLAY or log commands do you run first?

Frequently Asked Questions

Test Your Knowledge