Queue manager certificate administration

IBM certificate management policy

When a queue manager is created a default certificate chain is added to the queue manager's key store and trust store. The key store contains the certificate used by the queue manager and the trust store contains the intermediate and root CA certificates used to sign the queue manager certificate. The default certificate is configured for use on the queue manger, the MQ Console and REST APIs. Only the queue manager certificate can be replaced.

Certificates can be viewed in the service by selecting a queue manager and clicking the Key store tab. The image below shows a certificate in the key store, the icons (which are greyed out when not in use) from left to right represent:

• Queue manager default certificate (used when no explicit certificate is chosen in configuration)
• Used in TLS channel configuration
• Used in AMS channel configuration
• Used by MQ Console and REST APIs

The default certificate has a 90 day expiration period. When nearing expiry the following process is invoked by the service:

• Approximately 30 days before expiration a new certificate is added to the queue manager key store
  • Queue managers that have not been configured to enable TLS will use the new certificate by default
  • Queue managers that are configured to use TLS will continue to use the old certificate, the new certificate is made available for use
  • The MQ Console and REST APIs for existing queue managers continue to the use the old certificate
  • The MQ Console and REST APIs for new queue managers use the new certificate
• Approximately 14 days before expiration the new certificate becomes the default
  • Queue managers that are configured to use TLS or AMS will have the default certificate replaced with the new certificate (MQ clients will be disconnected for a short time, while the security configuration is refreshed)
  • The MQ Console and REST APIs use the new certificate
  • The old certificate is removed from the queue manager key store

Queue managers that have been configured to use a customer generated certificate remain unaffected by the above process. Customer generated certificate expiry is the responsibility of the queue manager administrator

Certificates originally had an expiration period of 1 year. This has been reduced to 90 days

Handling certificate expiry

The IBM MQ on Cloud service will provide notifications in the service console user interface when IBM provided certificates near expiry. If you wish to configure notification of certificate expiry via other channels such as Slack or PagerDuty then please use the IBM Cloud Certificate Manager service.

Within 30 and 14 days of expiry increasingly severe warnings are displayed in the queue manager list view and on the queue manager details pages. During this period TLS and AMS enabled MQ clients and connected queue managers will require their trust stores to be updated to include the new certificate. To download the new certificate from the service follow these steps:

1. Open the Key store tab for the required queue manager
2. Select the ... icon on the new certificate
3. Click the Download public certificate button to download the PEM file
4. Import the certificate into the MQ client trust store

An example of importing a certificate into another queue manager trust store

# First convert the PEM file to pkcs12
# Choose a password when prompted
openssl pkcs12 -export -out qmgrcert_YYYYMM.pfx -in qmgrcert_YYYYMM.pem -nokeys

# Import the certificate into the queue manager trust store
runmqckm -cert -import -file qmgrcert_YYYYMM.pem -type pkcs12 -target /var/mqm/qmgrs/<QM>/ssl/key.kdb -target_pw <password> -target_type cms -label <label>

An example of importing a certificate into a Java client trust store

# First convert the PEM file to DER
openssl x509 -outform der -in qmgrcert_YYYYMM.pem -out qmgrcert_YYYYMM.der

# Import the certificate into the Java trust store
keytool -import -alias <label> -keystore cacerts -file qmgrcert_YYYYMM.der

Once the MQ client or connected queue manager trust stores have been updated, the IBM MQ on Cloud queue manager can be configured to use the new certificate.

1. Open the Key store tab for the required queue manager
2. Select the ... icon on the new certificate
3. Click the Manage button
4. Select the TLS and AMS configuration required
5. Now refresh the queue manager SSL Security:
   1. On the queue manager page, select Configuration.
   2. Select the Security tab.
   3. Select the three dots, then Refresh SSL
   4. Confirm by clicking Refresh

If using a customer generated certificate a new version will need to be imported into the queue manager key store before the current certificate expires. TLS and AMS enabled MQ clients and connected queue managers will also require the new certificate to be added to their trust stores before the IBM MQ on Cloud queue manager configuration is updated to use the new certificate. See the section below for details on using customer generated certificates.

Using your own certificate

IBM MQ on Cloud supports the use of customer generated certificates when using TLS to connect the queue manager. Customer generated certificates need to be imported into the queue manager key store in the PEM format. Both public certificate and private key need to be contained in the same file.

In some organizations TLS signed certificates are generated for you by a central certificate authority (CA). In this scenario the CA public certificates must also be included in the PEM file in the order:

• private key
• customer generated certificate
• signer CA certificates

The example below generates a self-signed client certificate and private key and merges them into a single PEM file.

# Generate a new self-signed public certificate and private key
# (fill in the segments of the certificate as you wish when prompted)
openssl req -newkey rsa:2048 -nodes -keyout clientKey.pem -x509 -days 365 -out clientCert.pem

# Combine the private key and public certificate into a single file
cat clientKey.pem > clientCombined.pem
cat clientCert.pem >> clientCombined.pem

If the private key is encrypted you will need to decode it before importing it

Encrypted private keys look like this:

*-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC

To decrypt the private key run the following command supplying the passphrase when prompted.

openssl rsa -in [encrypted.key] -out [decrypted.key]

To import your certificate into the queue manager key store:

1. In the service select the queue manager to configure
2. Click on the Key store tab
3. Click on the Import button
4. Click Browse Files and select your PEM file
5. Click Next
6. Give your certificate a label and click Save
7. Tick the box indicating you understand a security refresh is required and click Finish
8. Now refresh the queue manager SSL Security:
   1. On the queue manager page, select Configuration.
   2. Select the Security tab.
   3. Select the three dots, then Refresh SSL
   4. Confirm by clicking Refresh

Your certificate can now be used when configuring TLS and AMS for your queue manager.

Using certificates for TLS

For details on how to use certificates for TLS see this documentation

Using certificates for AMS

For details on how to use certificates for AMS see this documentation