Digital Certificates

Digital certificates are the identity documents IBM MQ presents during TLS handshakes. Each certificate contains a public key, subject distinguished name (DN), validity dates, and a signature from a certificate authority (CA). The queue manager stores its own personal certificates in a key repository referenced by SSLKEYR and selects one using CERTLABL or channel SSLCERTLABL. Partner queue managers and clients present their certificates; GSKit validates chains against trusted CA certificates in the repository or SSLKEYREP. When certificates expire or labels mismatch, channels fail before a single business message moves—often during a weekend certificate rotation that missed one queue manager in a cluster. This tutorial explains personal versus CA certificates, how labels work, certificate signing requests, importing and trusting partners, hostname and DN matching with CHLAUTH SSLPEER, renewal calendars, and beginner-friendly troubleshooting of the most common certificate errors in IBM MQ estates.

Personal Versus CA Certificates

A personal certificate (also called a server or client certificate depending on role) proves the identity of this endpoint—CN=qm1.example.com for a queue manager listener. The private key must remain in the key repository and never leave in cleartext. A CA certificate is not used as the listener identity; it signs personal certificates and allows MQ to trust partners signed by the same enterprise CA. Import your company root and intermediate CAs into the trust store so remote partner certificates validate. Self-signed personal certificates are for lab only unless both ends import each other as trusted.

Key Repository and Labels

ALTER QMGR SSLKEYR('/path/key.kdb') points to the key database. Multiple personal certificates can coexist—production, test, or separate listeners. CERTLABL('ibmwebspheremqmq1') selects the default for inbound connections. DEFINE CHANNEL with SSLCERTLABL overrides for a specific channel when one queue manager needs multiple identities. DISPLAY QMGR CERTLABL lists labels; runmqakm or gskcapicmd -cert -list shows repository contents on distributed systems. Wrong label is a frequent handshake failure when operations imports a new cert but forgets to point the channel at the new label name.

1
2
3
4
5
6
7
8
9
* After import (platform tools vary):
ALTER QMGR SSLKEYR('/var/mqm/qmgrs/QM1/ssl/key.kdb')
ALTER QMGR CERTLABL('qm1_prod_2027')
DEFINE CHANNEL('PARTNER.SVRCONN') CHLTYPE(SVRCONN) TRPTYPE(TCP) +
  SSLCIPH(TLS_RSA_WITH_AES_256_CBC_SHA256) +
  SSLCERTLABL('qm1_prod_2027') SSLCAUTH(REQUIRED)
* Partner CHLAUTH example:
SET CHLAUTH('PARTNER.SVRCONN') TYPE(SSLPEERMAP) +
  SSLPEER('CN=partnerapp,O=Corp,C=US') ADDRESS('*') MCAUSER('mqpartner') ACTION(MAP)

Creating and Renewing Certificates

Enterprise teams usually submit a CSR to internal PKI and receive a signed certificate chain. Lab teams may use runmqakm -cert -create for self-signed. Renewal: generate new key pair or reuse per policy, obtain new signed cert, import before old expiry, update CERTLABL if label name includes year, restart channels, verify partner trust stores include the same CA. Maintain a spreadsheet of expiry per queue manager hostname and environment.

Distinguished Names and CHLAUTH

The SSLPEER field in CHLAUTH rules matches parts of the partner certificate DN—CN=app01, O=Corp, or wildcards per IBM syntax. When PKI reissues with a new CN, SSLPEERMAP rules must update before cutover or mutual TLS partners fail. Map to MCAUSER for OAM consistency; the certificate proves identity, MCAUSER is what setmqaut targets for queue permissions.

Explainer: ID Card for the Computer

A digital certificate is a plastic ID card with a photo only the issuer (CA) can forge. TLS shows the card through the window; CHLAUTH reads the name on the card and decides which MQ userid to use.

Trust Stores and Partner Certificates

When a remote queue manager connects, GSKit builds a chain from its personal certificate to a trusted CA. If your repository lacks the partner CA, handshake fails even with a valid corporate cert. Import partner intermediate and root CAs during onboarding projects. SSLKEYREP on some configurations holds additional CA material—follow IBM documentation for your platform layout.

Hostname and SAN Validation

Clients verifying the server certificate compare CONNAME hostname to certificate Subject Alternative Name (SAN) or CN. Certificate for qm1.prod.example.com fails when clients connect to 10.0.0.5 unless SAN includes IP or DNS matches. Plan DNS names in certificate requests to match MQ CONNAME and connection factory host strings.

Troubleshooting Certificate Issues

1. DISPLAY QMGR SSLKEYR CERTLABL; list certs in repository.
2. Check notAfter expiry date on personal cert.
3. Confirm channel SSLCERTLABL matches existing label.
4. Verify partner CA in trust store.
5. Compare SSLPEER in CHLAUTH to actual cert DN from trace.
6. Align cipher and protocol after cert is trusted.

Explain Like I'm Five: Digital Certificates

A certificate is a special name tag signed by the school principal so strangers know you really belong to the school. TLS checks the tag before letting you in the building.

Practice Exercises

Exercise 1

Document CSR fields needed for a queue manager listener cert with SAN.

Exercise 2

Write renewal steps including CHLAUTH SSLPEER review.

Exercise 3

List differences between personal cert and CA cert in your repository.

Frequently Asked Questions

Test Your Knowledge