SSLPEER Mapping

TLS on an IBM MQ channel encrypts bytes on the wire, but encryption alone does not tell the queue manager which application or partner queue manager is connecting. SSLPEER mapping—CHLAUTH TYPE(SSLPEERMAP)—closes that gap by matching the distinguished name (DN) on the peer X.509 certificate to a CHLAUTH rule and optionally assigning an MCAUSER. Operations teams that enable SSLCIPH and SSLCAUTH but skip SSLPEERMAP often discover that connections still run as a powerful channel MCAUSER, or that renewed certificates silently break production on the Monday after PKI rotation. This tutorial is a beginner-focused deep dive: how SSLPEER strings work, how they differ from ADDRESSMAP and QMGRMAP, designing rules per SVRCONN and RCVR, certificate renewal runbooks, wildcards versus explicit DNs, and troubleshooting when BINDING fails after handshake.

Where SSLPEERMAP Sits in the Bind Flow

An inbound connection hits the listener, negotiates TLS, and completes the handshake. Only then does the queue manager evaluate channel authentication records if CHLAUTH is ENABLED. SSLPEERMAP rules run in the context of the channel name and other CHLAUTH types defined for your release—consult IBM documentation for precedence rather than assuming IP rules always win over cert rules. When a rule matches, ACTION(ALLOW) permits the bind to continue; ACTION(BLOCK) rejects with a logged event; USERSRC(MAP) with MCAUSER sets the effective user ID for puts and gets on that channel instance. If no SSLPEERMAP matches and defaults block unknown peers, the channel never reaches RUNNING even though tcpdump shows a successful TLS session.

Reading a Certificate DN

A typical partner certificate subject looks like CN=payments.prod,O=Example Corp,L=London,C=GB. IBM MQ stores and compares the DN as a single string; your SSLPEER pattern must align with what the queue manager actually receives—ordering of RDN components, spacing, and omitted fields matter. Export the live cert from the partner or use DISPLAY CHANNEL with SSL peer fields where your release exposes them. Compare character-for-character to SET CHLAUTH SSLPEER. Common mistakes include matching CN=payments.prod when PKI issued CN=payments.prod.example.com, or omitting the organizational unit that corporate CA templates add. Document the canonical DN format your security team uses so application teams do not paste openssl output with different delimiter styles into MQSC scripts.

Creating SSLPEERMAP Rules

1
2
3
4
5
6
7
8
9
ALTER QMGR CHLAUTH(ENABLED)
DEFINE CHANNEL('PAYMENTS.IN') CHLTYPE(RCVR) TRPTYPE(TCP) +
  SSLCIPH(TLS_RSA_WITH_AES_256_CBC_SHA256) SSLCAUTH(REQUIRED) +
  MCAUSER('nobody')
SET CHLAUTH('MAP.PAYMENTS.PROD') TYPE(SSLPEERMAP) +
  SSLPEER('CN=payments.prod,O=Example Corp,C=GB') +
  MCAUSER('apppay') USERSRC(MAP) ACTION(ALLOW) +
  CHNAME('PAYMENTS.IN') DESCR('Prod payments cert')
DISPLAY CHLAUTH('MAP.PAYMENTS.PROD') ALL

In this pattern the channel MCAUSER is a low-privilege placeholder; only connections presenting the mapped certificate run as apppay with put authority on business queues. SSLCAUTH(REQUIRED) on RCVR forces the remote SDR or client to present a client certificate—without it, SSLPEERMAP has nothing to match. Pair channel SSLCIPH with partner cipher overlap; cipher mismatch fails before CHLAUTH is reached. Grant apppay explicit +put on intended QLOCAL objects and deny broad +all authority.

SSLPEER Pattern Strategies

Explicit full DN rules are easiest to audit in compliance reviews: one rule per application certificate. Wildcard or partial DN patterns reduce operational load when dozens of microservices share the same O= and C= but different CN values—verify wildcard support on your exact MQ fix pack in a lab because syntax errors create accidental blocks. Some estates maintain separate rules per environment: CN=payments.dev maps to apppaydev, CN=payments.prod maps to apppay. Never map multiple unrelated applications to one MCAUSER unless your OAM model intentionally treats them as the same security principal.

SVRCONN Versus Message Channels

Microservices connecting through SVRCONN channels are the most common SSLPEERMAP consumers: each service mesh identity or Kubernetes workload certificate maps to a dedicated MCAUSER with access only to its queues. On point-to-point RCVR channels, the partner queue manager or integration appliance presents a client cert during mutual TLS; SSLPEERMAP identifies that appliance even when ADDRESSMAP would allow an entire subnet. Cluster channels may still use QMGRMAP for member names while SSLPEERMAP handles administrative client tools—layer controls rather than choosing only one.

Certificate Renewal and PKI Events

1. Thirty days before expiry, generate new cert in PKI with planned subject DN.
2. Update queue manager key repository and partner trust stores in non-production.
3. Add or update SET CHLAUTH SSLPEER before cutover if DN changes.
4. Test BINDING and RUNNING with DISPLAY CHSTATUS and a test put.
5. Cut over production during a window; monitor CHLAUTH events.
6. Remove obsolete SSLPEER rules after all partners migrated.

If renewal reuses the same DN, you may only update the certificate file in the key repository without CHLAUTH changes—still test because some CAs change serial numbers only while others add new subject alternative names that affect matching on certain releases. Revoked certificates should fail when CRL or OCSP AUTHINFO objects are configured; SSLPEERMAP is not a substitute for revocation checking.

Combining SSLPEERMAP With Other Controls

• Firewall restricts who can reach the listener port.
• ADDRESSMAP limits source IP for defense in depth.
• SSLPEERMAP identifies the certificate holder.
• BLOCKUSER denies dangerous asserted user IDs on SVRCONN.
• OAM grants least privilege to mapped MCAUSER on objects.

A penetration test that reaches the listener with a valid cert stolen from a compromised partner still passes SSLPEERMAP—monitoring and short-lived certs reduce that risk. Internal fraud scenarios sometimes require mapping one cert to one MCAUSER per application owner for accountability in SMF or audit logs.

Troubleshooting SSLPEERMAP Failures

Symptom: channel in BINDING, TLS appears fine in network capture, then disconnect. Search the error log for CHLAUTH and the rule name. DISPLAY CHLAUTH shows SSLPEER; compare to actual DN. Symptom: connects as wrong MCAUSER—another rule may map first per precedence; review all SSLPEERMAP and USERMAP rules for that CHNAME. Symptom: works in test but not prod—environment-specific cert or missing intermediate CA in SSLKEYR. Symptom: intermittent failure—load balancer terminating TLS and re-encrypting with a different backend cert changes the DN the queue manager sees unless you use passthrough mutual TLS end-to-end.

Explainer: Photo ID at the Door

TLS is the locked door. SSLPEER mapping is the guard comparing the photo on the ID badge to the approved guest list before assigning a visitor badge (MCAUSER) that only opens certain rooms.

Explain Like I'm Five: SSLPEER Mapping

SSLPEER mapping means MQ checks the name on your friend's special card and only lets them in if it matches the name we wrote on our allowed list—and then gives them the right color wristband for what they are allowed to touch.

Practice Exercises

Exercise 1

Write SET CHLAUTH for one SVRCONN with explicit SSLPEER and MCAUSER apptest; list OAM grants needed on QLOCAL TEST.IN.

Exercise 2

Partner renewed cert with new CN—document DISPLAY and ALTER steps without disabling CHLAUTH globally.

Exercise 3

Compare three-way design: ADDRESSMAP only, SSLPEERMAP only, both for a B2B RCVR on the internet.

Frequently Asked Questions

Test Your Knowledge