SSL failures on IBM MQ stop encrypted channels before messages flow. Operations sees RETRY loops, listeners accepting TCP then closing, or client errors referencing GSKit and TLS. Unlike authority problems that return 2035 after connect, TLS problems usually block the session earlier—though the symptom from the business view is the same: messages not moving. This tutorial is a troubleshooting guide for SSL failures: how TLS fits on message channels and SVRCONN, reading AMQ SSL messages, cipher and certificate checks, SSLCAUTH and mutual TLS, key repository verification with runmqakm, coordinating with PKI teams on renewal, and when to use GSKit trace versus AMQERR alone.
When SSLCIPH is set on a channel definition, GSKit performs TLS after TCP connect and before MQ channel protocol exchange. The queue manager uses SSLKEYR (key repository) and CERTLABL (personal certificate label). The partner must trust your CA and present a certificate if SSLCAUTH is REQUIRED. Channel authentication (CHLAUTH) may map certificate DN to MCAUSER after TLS succeeds. Failure at any TLS step prevents RUNNING—messages remain on XMITQ for sender channels.
| Attribute | Purpose | If wrong |
|---|---|---|
| SSLCIPH | Cipher specification | Handshake failure, no shared cipher |
| SSLCAUTH | Optional vs required peer cert | REQUIRED without client cert fails |
| CERTLABL | Which personal cert to present | Wrong or missing server identity |
| SSLKEYR | Key repository path | Cannot load keys or trust store |
One side offers only TLS 1.3 ciphers; the other allows legacy suites. SSLCIPH strings must be compatible. Lab test: temporarily align both sides to a known-good cipher from IBM documentation, confirm connect, then tighten to production policy.
Partner cert signed by a CA not in your kdb, or expired intermediate. Import missing CA certificates as trusted, renew expired certs, verify runmqakm -cert -list shows valid dates. Corporate PKI rotations often break integrations when only the leaf cert is updated but not the chain on the peer.
Multiple certs in kdb—wrong CERTLABL presents the wrong DN to CHLAUTH SSLPEER rules. After renewal, label name may change; update ALTER CHANNEL and QMGR CERTLABL consistently.
Clients verifying hostname against certificate CN/SAN may fail when connecting via load balancer DNS name. Align CONNAME, certificate SAN, and verification policy per enterprise standards.
1234DISPLAY CHANNEL('PARIS.TO.LONDON') SSLCIPH SSLCAUTH DISPLAY CHSTATUS('PARIS.TO.LONDON') LASTCHLERR SSLCIPH runmqakm -cert -list -db /var/mqm/qmgrs/QM1/ssl/key.kdb -stashed * Partner must trust your CA; you must trust theirs
Expired certificate Tuesday 00:00 UTC often causes synchronized retry loops on all TLS channels. Certificate monitoring should fire before expiry. If loops already run, renew cert, refresh kdb, restart or reset channels, verify RUNNING before closing the incident. Do not only increase LONGTMR.
Application clients use JSSE, Schannel, or MQ client GSKit with parallel requirements: trust store, cipher suites, and sometimes client cert for mutual TLS. A channel may work server-to-server while Java client fails if trust store lacks corporate CA. Collect client SSL debug and server AMQERR together.
TLS is the lock on the envelope carrying MQ data. SSL failure means the partners cannot agree on the lock type or one key is expired—so the post office refuses to accept the envelope even though the address (CONNAME) is correct.
You and your friend have secret decoder rings that must match. If your ring is broken (expired cert) or the wrong shape (cipher), you cannot talk, even if you are shouting the right channel name.
Lab: set mismatched SSLCIPH on RCVR only; capture AMQERR and LASTCHLERR.
Build certificate renewal checklist: kdb import, CERTLABL, channel reset, verify RUNNING.
List three AMQ message patterns you will grep during SSL incidents.
1. SSL failure often leaves channel in:
2. SSLCIPH mismatch means:
3. Expired cert fix requires:
4. AMQ9638 class messages relate to: