Key Repositories

A key repository is the secure filing cabinet where IBM MQ keeps TLS credentials for a queue manager. Without a correctly configured repository, channels cannot present a server certificate, mutual TLS cannot request a client certificate, and partners cannot validate your queue manager identity. On distributed systems the familiar files are key.kdb and key.sth under the queue manager ssl directory; ALTER QMGR SSLKEYR tells the queue manager which kdb to open at startup. Personal certificates and their private keys live inside; trusted certificate authority (CA) certificates allow GSKit to verify remote partners. Beginners confuse the repository with individual certificate files on disk—MQ expects the kdb format managed by GSKit tools, not loose .pem files dropped without import. This tutorial explains SSLKEYR and SSLKEYREP, creating and populating a repository with runmqakm, certificate labels, trust versus personal entries, permissions on filesystem directories, backup and DR, rotation impact, and troubleshooting when AMQ reports key database or label errors during handshake.

SSLKEYR and Queue Manager Binding

When the queue manager starts, it reads SSLKEYR. If the path is wrong or permissions deny read, TLS channels fail immediately. DISPLAY QMGR SSLKEYR shows the current setting. Changing SSLKEYR to a new kdb requires importing all still-needed certificates and updating CERTLABL defaults. Plan maintenance windows because active channels may need restart. On z/OS, key rings in ICSF or RACF replace kdb—conceptually the same role, different commands.

Creating and Opening a Repository

1
2
3
4
runmqakm -keydb -create -db /var/mqm/qmgrs/QM1/ssl/key.kdb -pw '***' -stash
runmqakm -cert -add -db /var/mqm/qmgrs/QM1/ssl/key.kdb -stashed -label ca_root -file ca_root.cer -format ascii
runmqakm -cert -import -db /var/mqm/qmgrs/QM1/ssl/key.kdb -stashed -label qm1_prod -file qm1_signed.p12 -pw '***' -type pkcs12
ALTER QMGR SSLKEYR('/var/mqm/qmgrs/QM1/ssl/key.kdb') CERTLABL('qm1_prod')

The -stash option creates the .sth file so the queue manager can open the kdb without interactive password at runtime—secure the directory so only mqm and administrators read it. Import order matters: trust CAs before personal certificates so chain validation succeeds during test handshakes. PKCS12 bundles often include the private key and chain in one step for lab builds; production PKI may deliver separate .cer and key files per your security team format.

Personal Versus Trusted Certificates in the kdb

Personal entries include a private key and are referenced by CERTLABL for outbound and inbound TLS identity. Trusted entries are CA certificates without your private key—they tell MQ to accept partners signed by that CA. Missing intermediate CA in the kdb causes valid-looking partner certs to fail chain building. Import the full chain your PKI team provides, not only the leaf CA.

Labels and Multiple Identities

One kdb can hold qm1_prod, qm1_dr, and test labels for different channels. DEFINE CHANNEL SSLCERTLABL selects per channel. Default ALTER QMGR CERTLABL applies when the channel does not override. After import, runmqakm -cert -list -db ... -stashed confirms labels. Mismatch between label in channel and list output is a top handshake failure in operations tickets.

Filesystem Security and Backup

• Restrict directory to mqm group and root; no world read on .kdb, .sth, or .p12 imports.
• Encrypt backups; key repository loss forces full PKI reissuance.
• Document stash password location in vault, not tickets.
• Replicate kdb to DR queue manager before cutover tests.

Explainer: Safe for Keys

The key repository is a locked safe in the queue manager office. Personal certificates are your ID cards in the safe; CA certificates are the list of which issuing offices you trust. The stash file is the combination only the queue manager should know.

SSLKEYREP and Trust Stores

Some configurations separate additional CA material in SSLKEYREP. Whether you use one kdb for everything or split trust depends on enterprise standards and IBM guidance for your platform version. Consistency across cluster members prevents one node trusting a partner others reject.

Troubleshooting Repository Problems

1. DISPLAY QMGR SSLKEYR — path exists and readable.
2. List certs with runmqakm -cert -list.
3. Verify CERTLABL on QMGR and channel matches a listed label.
4. Confirm stash password valid if kdb password protected.
5. Re-import CA chain if partner cert fails validation.

Explain Like I'm Five: Key Repositories

The key repository is a locked box where the queue manager keeps its TLS keys and the list of which other computers it trusts.

Practice Exercises

Exercise 1

Write steps to create a lab kdb and import a self-signed cert.

Exercise 2

List backup and restore checks for DR queue manager TLS.

Exercise 3

Explain stash file risk if copied to unsecured share.

Frequently Asked Questions

Test Your Knowledge