- 9 minutes to read

FAQ - IBM MQ SSL Certificate Configuration

Configure secure SSL/TLS connections between Nodinite IBM MQ Monitoring Agent and IBM MQ Queue Managers with proper certificate setup.

Overview

IBM MQ SSL/TLS authentication uses different certificate storage mechanisms depending on agent version and IBM MQ version. This FAQ addresses common certificate configuration challenges for both legacy and modern deployments.

What's on This Page:

  • Certificate Storage by Version - Where certificates are stored (.kdb files vs Windows Certificate Store)
  • Certificate Requirements - Server Auth vs Client Auth EKU requirements
  • Conversion Procedures - How to convert Windows certificates to IBM MQ Key Database format
  • Common SSL Errors - Troubleshooting handshake failures and configuration issues
  • CipherSpec Compatibility - Matching cipher suites between Queue Manager and agent

Certificate Storage by Agent Version

Legacy Agent (.NET Framework 4.8 targeting IBM MQ ≤ 9.3)

Certificate Storage: IBM MQ Key Database files (.kdb)

  • Location: File system path (e.g., C:\MQ\KeyDB\key.kdb)
  • Management Tools: runmqakm or ikeycmd utilities
  • Does NOT use: Windows Certificate Store
  • Configuration: SSL Key Repository Path in agent configuration points to .kdb file path without extension

Example Configuration:

SSL Key Repository Path: C:\MQ\KeyDB\key
(Note: Path excludes .kdb extension - IBM MQ adds it automatically)

Modern Agent (.NET 9/10 targeting IBM MQ ≥ 9.5)

Certificate Storage: Windows Certificate Store OR IBM MQ Key Database files (.kdb)

  • Primary: Windows Certificate Store (CertStoreLocation)
  • Backward Compatibility: Still supports .kdb files for migration scenarios
  • Management: Windows Certificate Manager (certmgr.msc) or PowerShell
  • Configuration: Can point to Windows Certificate Store or .kdb file path

Example Configuration (Windows Certificate Store):

SSL Key Repository Path: *SYSTEM
CipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256
Certificate Label: ibmwebspheremq<qmgr_name> (lowercase)

Certificate Requirements

Server-Side (IBM MQ Queue Manager)

Requirement Value Notes
EKU Server Authentication (1.3.6.1.5.5.7.3.1) Authenticates Queue Manager to connecting clients
Key Usage DigitalSignature, KeyEncipherment Required for SSL/TLS handshake
Certificate Store IBM MQ Key Database on Queue Manager server Configured in Queue Manager SSL configuration
Certificate Label ibmwebspheremq<qmgr_name> Must match Queue Manager name (case-sensitive, usually lowercase)

Client-Side (Nodinite IBM MQ Monitoring Agent)

Requirement Value Notes
EKU Client Authentication (1.3.6.1.5.5.7.3.2) Authenticates agent to Queue Manager (mutual TLS)
Key Usage DigitalSignature Client certificates only need to sign authentication challenges
Certificate Store .kdb files (legacy) OR Windows Certificate Store (modern) Version-dependent (see above)
Certificate Label Custom label or default Specified in agent SSL configuration

Warning

Mutual TLS Requirement: Most enterprise IBM MQ deployments require both server and client certificates. The Queue Manager authenticates the agent (client cert) AND the agent authenticates the Queue Manager (server cert).

Converting Windows Certificates to IBM MQ Key Database

Prerequisites

  • IBM MQ client libraries installed (includes runmqakm or ikeycmd)
  • Windows certificate exported as .pfx (PKCS#12) with private key
  • Administrative privileges

Step 1: Export Certificate from Windows Certificate Store

Using Certificate Manager (certmgr.msc):

  1. Open Certificate Manager → Personal → Certificates
  2. Right-click certificate → All Tasks → Export
  3. Choose Yes, export the private key
  4. Select Personal Information Exchange - PKCS #12 (.PFX)
  5. Set password and save (e.g., client-cert.pfx)

Using PowerShell:

# Export certificate with private key
$cert = Get-ChildItem Cert:\LocalMachine\My\<thumbprint>
$password = ConvertTo-SecureString -String "YourPassword" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath "C:\Temp\client-cert.pfx" -Password $password

Step 2: Create IBM MQ Key Database

Using runmqakm (recommended for IBM MQ 9.0+):

:: Create new Key Database
runmqakm -keydb -create -db "C:\MQ\KeyDB\key.kdb" -pw YourKdbPassword -type cms -stash

:: Import certificate from PFX
runmqakm -cert -import -file "C:\Temp\client-cert.pfx" -pw YourPfxPassword ^
  -target "C:\MQ\KeyDB\key.kdb" -target_pw YourKdbPassword -target_type cms ^
  -label "nodiniteclient"

:: List certificates (verify import)
runmqakm -cert -list -db "C:\MQ\KeyDB\key.kdb" -pw YourKdbPassword -type cms

Using ikeycmd (legacy tool for older IBM MQ):

:: Create new Key Database
ikeycmd -keydb -create -db "C:\MQ\KeyDB\key.kdb" -pw YourKdbPassword -type cms -stash

:: Import certificate from PFX
ikeycmd -cert -import -file "C:\Temp\client-cert.pfx" -pw YourPfxPassword ^
  -target "C:\MQ\KeyDB\key.kdb" -target_pw YourKdbPassword -target_type cms ^
  -label "nodiniteclient"

Step 3: Import CA Certificate Chain (if needed) 

:: Import root CA certificate
runmqakm -cert -add -file "C:\Temp\root-ca.cer" -db "C:\MQ\KeyDB\key.kdb" ^
  -pw YourKdbPassword -type cms -label "RootCA"

:: Import intermediate CA certificate
runmqakm -cert -add -file "C:\Temp\intermediate-ca.cer" -db "C:\MQ\KeyDB\key.kdb" ^
  -pw YourKdbPassword -type cms -label "IntermediateCA"

Step 4: Configure Agent SSL Settings

In Nodinite IBM MQ Agent Configuration:

SSL Key Repository Path: C:\MQ\KeyDB\key
(Note: Omit .kdb extension)

SSL Certificate Label: nodiniteclient
CipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256
SSL Peer Name Property: CN=<QueueManagerHost>

Tip

Password Stash File: The -stash option creates a .sth file alongside the .kdb file, allowing IBM MQ to access the Key Database without entering the password. This is required for automated agent connections.

CipherSpec Configuration

Common CipherSpecs (IBM MQ 9.x)

CipherSpec Security Level TLS Version Notes
TLS_RSA_WITH_AES_256_GCM_SHA384 High TLS 1.2 Recommended for IBM MQ 9.1+
TLS_RSA_WITH_AES_128_CBC_SHA256 Medium TLS 1.2 Good balance of security and compatibility
TLS_RSA_WITH_AES_256_CBC_SHA256 High TLS 1.2 Strong encryption, widely supported
ECDHE_RSA_AES_128_CBC_SHA256 High TLS 1.2 Forward secrecy, requires EC certificates
TLS_AES_256_GCM_SHA384 High TLS 1.3 IBM MQ 9.2+ only

Important

CipherSpec Must Match: The CipherSpec configured in the agent must match the CipherSpec configured on the IBM MQ Queue Manager channel. Mismatched cipher suites cause SSL handshake failures.

Checking Queue Manager CipherSpec 

echo "DISPLAY CHANNEL(<ChannelName>)" | runmqsc <QueueManagerName>

Look for SSLCIPH attribute in output.

Common SSL Errors & Solutions

Error: MQRC_SSL_INITIALIZATION_ERROR (2393)

Cause: Agent cannot access certificate or Key Database file.

Solutions:

  • Legacy Agent (.NET Framework 4.8):

    • Verify .kdb file exists at specified path
    • Ensure .sth (stash) file exists alongside .kdb file
    • Check file permissions - agent service account needs read access
    • Verify SSL Key Repository Path excludes .kdb extension

  • Modern Agent (.NET 9/10):

    • Verify certificate exists in Windows Certificate Store (Cert:\LocalMachine\My)
    • Ensure agent service account has read permissions on private key
    • Check that certificate has proper EKU (Client Authentication)

Error: MQRC_SSL_PEER_NAME_ERROR (2398)

Cause: Queue Manager certificate Distinguished Name doesn't match SSL Peer Name Property.

Solutions:

  1. Check Queue Manager certificate DN:

    runmqakm -cert -details -db "C:\MQ\QMGR\KeyDB\key.kdb" -pw password -label ibmwebspheremqqmgr1

  2. Update SSL Peer Name Property in agent configuration to match:

    CN=qmgr.example.com,O=YourOrg,C=US

  3. Or use wildcard pattern:

    CN=*.example.com,O=YourOrg

Error: MQRC_CHANNEL_SSL_ERROR (2371)

Cause: SSL handshake failed - usually CipherSpec mismatch or certificate validation failure.

Solutions:

  1. Verify CipherSpec Match:

    :: Check Queue Manager channel CipherSpec
echo "DISPLAY CHANNEL(<ChannelName>)" | runmqsc <QMgrName>

    Ensure agent CipherSpec matches Queue Manager channel SSLCIPH value.

  2. Verify Certificate Chain:

    • Agent must trust Queue Manager's CA certificate
    • Queue Manager must trust agent's CA certificate (mutual TLS)
    • Import CA certificates into both Key Databases

  3. Check Certificate Expiration:

    runmqakm -cert -list -db "C:\MQ\KeyDB\key.kdb" -pw password -type cms

Error: MQRC_NOT_AUTHORIZED (2035)

Cause: SSL handshake succeeded, but Queue Manager rejected connection due to authorization.

Solutions:

  1. Verify Certificate DN Mapping:

    • Queue Manager maps certificate DN to MQ user
    • Check SSLPEER and SSLCAUTH on channel definition

  2. Grant Permissions:

    :: Allow connection for certificate DN
setmqaut -m <QMgrName> -t qmgr -p <UserMappedFromDN> +connect +inq

Testing SSL Connection

Test with IBM MQ Sample Programs 

:: Test SSL connection (replace placeholders)
amqsputc <QueueName> <QMgrName>

Set environment variables before testing:

Set environment variables before testing:

```cmd
set MQSSLKEYR=C:\MQ\KeyDB\key
set MQSSLRESET=0
set MQSAMP_USER_ID=<username>

Enable SSL Tracing (Troubleshooting)

Queue Manager side:

:: Enable SSL tracing
strmqtrc -m <QMgrName> -t ssl
:: Reproduce issue
:: Stop tracing
endmqtrc -m <QMgrName>
:: View trace
dmpmqtrc <TraceFile>

Agent side (.NET Framework 4.8):

Enable Debug logging in agent configuration and review agent log files for SSL handshake details.

SSL Configuration Checklist

Legacy Agent (.NET Framework 4.8)

  • IBM MQ Key Database (.kdb) created with runmqakm/ikeycmd
  • Stash file (.sth) exists alongside .kdb file
  • Client certificate with Client Authentication EKU imported
  • CA certificate chain imported (if using CA-signed certs)
  • SSL Key Repository Path configured without .kdb extension
  • SSL Certificate Label matches imported certificate label
  • CipherSpec matches Queue Manager channel configuration
  • SSL Peer Name Property matches Queue Manager certificate DN
  • Agent service account has read permissions on .kdb and .sth files

Modern Agent (.NET 9/10)

  • Certificate with Client Authentication EKU in Windows Certificate Store
  • Private key accessible to agent service account
  • CA certificate chain trusted (Trusted Root Certification Authorities)
  • SSL Key Repository Path configured (*SYSTEM or .kdb path)
  • SSL Certificate Label matches certificate label
  • CipherSpec matches Queue Manager channel configuration
  • SSL Peer Name Property matches Queue Manager certificate DN

Queue Manager Side (Both Versions)

  • Queue Manager certificate with Server Authentication EKU
  • Certificate label matches ibmwebspheremq<qmgr_name> (lowercase)
  • Channel has SSLCIPH defined
  • Channel has SSLCAUTH set appropriately (REQUIRED for mutual TLS)
  • Channel has SSLPEER configured to accept agent certificate DN
  • Agent's CA certificate imported (if using mutual TLS)
  • Proper permissions granted to mapped user (CONNECT, INQ)

Frequently Asked Questions

Q: Can I use the same certificate for multiple Queue Managers?
A: Not recommended. Best practice is one client certificate per agent instance. However, if using the same certificate, ensure the certificate's DN is authorized on all Queue Managers.

Q: Do I need mutual TLS (both server and client certificates)?
A: Depends on Queue Manager channel configuration. If SSLCAUTH is set to REQUIRED, mutual TLS is mandatory. If set to OPTIONAL, only server certificate is required.

Q: Can I migrate from .kdb files to Windows Certificate Store?
A: Yes, with modern agent (.NET 9/10). Export certificate from .kdb, import into Windows Certificate Store, update agent configuration to use *SYSTEM for SSL Key Repository Path.

Q: How do I troubleshoot "Certificate not found" errors? A:

  • Legacy Agent: Verify .kdb file path is correct and certificate label exists: runmqakm -cert -list -db path\key.kdb -pw password
  • Modern Agent: Verify certificate in Cert:\LocalMachine\My and label matches configuration

Q: What happens if certificates expire?
A: SSL connections fail immediately with handshake errors. Monitor certificate expiration dates and renew before expiration. Use Nodinite Certificate Monitoring to track Queue Manager certificate expiration.