SSLCAUTH (SSL Client Authentication)

Encrypting traffic with TLS is only half of channel security—knowing who connected matters as much as hiding data from eavesdroppers. SSLCAUTH on an IBM MQ channel definition tells the queue manager whether the remote party must present an X.509 client certificate during the TLS handshake. REQUIRED enforces mutual TLS for queue-manager links and client channels where certificate identity is the trust anchor. OPTIONAL allows handshakes without a client cert in some scenarios, which may be acceptable in lab environments but is rarely appropriate for production without additional controls. This tutorial explains SSLCAUTH values, how they interact with SSLCIPH and certificate stores, CHLAUTH SSLPEERMAP to MCAUSER, and troubleshooting certificate failures that block BINDING.

One-Way vs Mutual TLS

One-way TLS: the server presents a certificate; the client verifies the server. Mutual TLS: both sides present certificates. SSLCAUTH REQUIRED pushes mutual TLS for the channel— the partner queue manager or IBM MQ client must send a client cert signed by a CA the server trusts. Without it, the handshake fails and DISPLAY CHSTATUS shows BINDING or RETRY with TLS errors in the log.

Defining SSLCAUTH on Channels

1
2
3
4
5
6
7
8
9
10
ALTER QMGR SSLKEYR('key') SSLCERT('cert')
DEFINE CHANNEL('QM1.TO.QM2') CHLTYPE(SDR) TRPTYPE(TCP) +
  CONNAME('qm2.corp(1414)') XMITQ('XMIT.QM2') +
  SSLCIPH('TLS_RSA_WITH_AES_256_CBC_SHA256') SSLCAUTH(REQUIRED)
DEFINE CHANNEL('QM1.TO.QM2') CHLTYPE(RCVR) TRPTYPE(TCP) +
  SSLCIPH('TLS_RSA_WITH_AES_256_CBC_SHA256') SSLCAUTH(REQUIRED)
DEFINE CHANNEL('APP.SVRCONN') CHLTYPE(SVRCONN) TRPTYPE(TCP) +
  SSLCAUTH(REQUIRED) MCAUSER('appid')
SET CHLAUTH('APP.SVRCONN') TYPE(SSLPEERMAP) SSLPEER('CN=app1') +
  MCAUSER('appprod') ACTION(REPLACE)

Cipher names must match partner and platform support—use IBM supported cipher specs for your release rather than copying outdated examples. Both sides of SDR/RCVR need compatible SSLCIPH and consistent SSLCAUTH policy. Client applications need keystore configuration when SVRCONN has SSLCAUTH REQUIRED.

Explainer: Showing ID at the Door

TLS encryption is the locked envelope. SSLCAUTH REQUIRED is the bouncer demanding everyone show a photo ID card (client certificate), not just checking that the building has a lock.

Certificate Stores and Trust

• Queue manager key repository (SSLKEYR) holds certs and keys.
• Partner CA must be in trust store or handshake fails.
• Certificate expiry monitoring prevents surprise Sunday outages.
• Rotate certs in change windows with parallel trust during migration.

SSLPEERMAP and MCAUSER

After mutual TLS succeeds, CHLAUTH SSLPEERMAP maps distinguished name fields to MCAUSER so puts use least privilege. SSLCAUTH without mapping may leave connections authenticated at TLS layer but wrong for OAM. Document DN patterns per partner and application team.

Troubleshooting Handshake Failures

1. Confirm SSLCAUTH matches on both channel definitions.
2. Verify client cert present in partner keystore and not expired.
3. Check CA trust chain on both queue managers.
4. Align SSLCIPH—cipher mismatch fails before SSLCAUTH matters.
5. Read AMQ errors in error log on BINDING failure.

OPTIONAL in Non-Production

Labs sometimes use SSLCAUTH OPTIONAL while certificates are provisioned. Track technical debt—promote REQUIRED before production cutover. OPTIONAL with weak CHLAUTH defaults has caused breaches; treat as temporary.

Explain Like I'm Five: SSLCAUTH

SSLCAUTH REQUIRED means everyone must show their ID card, not just speak through a locked door.

Practice Exercises

Exercise 1

List steps to enable mutual TLS on SDR/RCVR between two queue managers.

Exercise 2

Handshake fails after cert renewal—five checks including SSLCAUTH and trust store.

Exercise 3

Why is SSLPEERMAP needed after SSLCAUTH REQUIRED?

Frequently Asked Questions

Test Your Knowledge