SSL errors on IBM MQ stop traffic before a single business message moves: the TCP connection may succeed, then GSKit fails the TLS handshake, and the channel never reaches RUNNING. Operations sees RETRY loops; developers may see connection exceptions without a clear 2035 because authority never ran. This encyclopedia page catalogs SSL and TLS failure modes—AMQ messages, MQRC codes, CHSTATUS symptoms, and the fix order that avoids whack-a-mole certificate imports. Pair this reference with tls-configuration and gskit tutorials for hands-on setup; use this page during incidents when you need a checklist, not a lecture.
Layer one: TCP and listener reachability. Layer two: TLS handshake (certificates, cipher, protocol version). Layer three: CHLAUTH and certificate DN mapping. Layer four: MCAUSER and OAM on SVRCONN after connect. SSL errors belong to layer two unless evidence points elsewhere. Misdiagnosing layer four while layer two fails wastes hours of setmqaut changes.
| MQRC | Name | Meaning | Typical action |
|---|---|---|---|
| 2393 | SSL_INITIALIZATION_ERROR | Cannot init TLS environment | SSLKEYR path, kdb permissions, GSKit install |
| 2397 | SSL_NOT_ALLOWED | Policy requires SSL; plain used | Set SSLCIPH on channel and client CCDT |
| 2395 | SSL_CERTIFICATE_ERROR | Cert validation failed | Chain, expiry, label, trust store |
| 2396 | SSL_PEER_NAME_ERROR | Peer name mismatch | SSLPEER, hostname verification rules |
AMQ9638 and AMQ9616 appear frequently in AMQERR during handshake failure. Text may reference cipher specification, bad certificate, or GSKit return codes. Copy the full line including any GSKit reason subcodes. AMQ9208 may follow if the channel enters retry after TLS failure—do not assume transport failure when SSL text is present in the same second.
| Message ID | Typical cause | Fix order |
|---|---|---|
| AMQ9638 | Handshake failure | Cipher, then cert chain, then label |
| AMQ9616 | GSKit / policy | FIPS mode, repository permissions |
| AMQ9208 | Channel retry after SSL fail | Fix TLS first, then channel reset |
| AMQ8077 | Post-TLS CHLAUTH block | After handshake green, tune CHLAUTH |
SSLCIPH names the cipher specification GSKit negotiates. Both ends must support a common suite. Enterprises standardize one string per environment documented in the connection handbook. After MQ upgrade, verify deprecated ciphers were not removed from GSKit while channels still reference old names. Compare DISPLAY CHANNEL SSLCIPH on both queue managers and client CCDT. Lab test with one known-good cipher before enabling stricter policy in production.
The queue manager uses SSLKEYR to locate the key database (kdb) and stash files. CERTLABL selects which personal certificate presents to the partner. Expired certificates produce clear not-after errors when you runmqakm -cert -list or openssl inspection on exported certs. Missing intermediate CA in the kdb causes partner trust failure even when your cert looks valid locally. Renewal requires import, label update if the DN changed, and coordinated partner trust store updates for mutual TLS.
12345# Distributed example checks DISPLAY QMGR SSLKEYR SSLCRYP DISPLAY CHANNEL('PARIS.TO.LONDON') SSLCIPH SSLCAUTH CERTLABL runmqakm -cert -list all -db /path/to/key.kdb -stashed DISPLAY CHSTATUS('PARIS.TO.LONDON') LASTCHLERR
SSLCAUTH OPTIONAL allows TLS encryption without requiring a client certificate. SSLCAUTH REQUIRED demands a partner cert trusted by your repository—common for B2B. If the sender presents no client cert while receiver requires one, handshake fails before MCAUSER matters. Client SVRCONN connections need personal certs in the client key repository when REQUIRED is set on the channel or CCDT.
DISPLAY CHSTATUS shows state RETRY, BINDING, or INACTIVE with LASTCHLERR text during SSL problems. Capture CHSTATUS from both ends with the same timestamp. PING CHANNEL does not replace TLS verification—it exercises MQ protocol after connect. Use a controlled START CHANNEL or client connect for SSL tests during change windows.
MQRC 2035 NOT_AUTHORIZED after RUNNING channel means OAM or put authority. SSL errors block RUNNING entirely. If your monitor shows channel RUNNING but PUT fails with 2035, SSL is not the current problem. If channel never RUNNING and AMQ9638 repeats, do not grant blanket mqm authority—fix TLS.
Messages travel inside an envelope only the post office can open if seals match. Wrong stamp (cipher), expired ID (certificate), or missing return address (client cert when required) means the post office rejects the bag before sorting mail into queues.
Two secret clubs have special keys to open a box. If the keys do not fit or one key expired, the box never opens and letters stay in the hallway.
Document SSLCIPH and CERTLABL for one production channel pair.
Provoke cipher mismatch in lab; capture AMQ9638 and LASTCHLERR.
Write renewal runbook: PKI ticket, import, test, partner trust update.
1. AMQ9638 usually indicates:
2. MQRC 2393 is:
3. Both channel ends need:
4. SSLCAUTH REQUIRED means: