TLS security for IBM MQ channels in IBM MQ as a Service

Reference documentation

The following links provide a handy reference for information on how to administer an IBM MQ as a Service queue manager using the standard administration tools. You may choose your preferred tool and follow the instructions in this document.

• Configuring administrator access for a queue manager
• Administering a queue manager using IBM MQ Console
• Administering a queue manager using IBM MQ Explorer and the runmqsc command line

Tasks on the IBM MQ as a Service queue manager

As mentioned earlier, enabling security on an IBM MQ channel requires configuring a cipher spec, and exchanging public certificates between the queue manager and the client (and for Mutual TLS, also between the client and the queue manager). The configuration of the cipher spec can be done using any of the three standard administration tools. The method for each is described below, so pick your preferred tool and follow the instructions. For access to the user credentials and certificate, the IBM MQ as a Service service console is required.

Using the IBM MQ as a Service console to gather credentials and certificates

1. Open the IBM MQ as a Service service console and locate your queue manager.
2. Gather the admin user's credentials. Select the Administration tab for your queue manager, you should note the user name, and follow the steps to download the API key (which is the password you will use to connect later). See Configuring administrator access for a queue manager.
3. Create an application user for the JMS and C applications. Select the Application credentials tab for your queue manager, and follow the process to add a new application credentials. Save the generated API key, which is the password for applications to connect with. See Configuring access for connecting an application to a queue manager.
4. Download the JSON CCDT description of your queue manager. Click the Connection Info button, and follow the instructions to download the CCDT form of the connection info. You might also want to download the text version, which is easier to read, and a useful source of the queue manager name and url.
   The CCDT file downloaded should look like this:

   {
   "channel": [
     {
     "name": "CLOUD.ADMIN.SVRCONN",
     "clientConnection": {
       "connection": [
       {
         "host": "myhost.cloud.ibm.com",
         "port": 31605
       }
       ],
       "queueManager": "MQ_ONE"
     },
     "transmissionSecurity": {
       "cipherSpecification": "ANY_TLS12_OR_HIGHER"
     },
     "type": "clientConnection"
     },
     {
     "name": "CLOUD.APP.SVRCONN",
     "clientConnection": {
       "connection": [
       {
         "host": "myhost.cloud.ibm.com",
         "port": 31605
       }
       ],
       "queueManager": "MQ_ONE"
     },
     "transmissionSecurity": {
       "cipherSpecification": "ANY_TLS12_OR_HIGHER"
     },
     "type": "clientConnection"
     }
   ]
   }

Using IBM MQ Console to alter the channels

1. Navigate to the Administration tab for your queue manager.
   
2. Ensure 'MQ Console' is selected and then click Launch MQ Console.
3. Click on Manage in the side menu to view your IBM MQ objects.
   
4. Click on Communication then App channels.
   
5. From the table, click the 3 dots for CLOUD.ADMIN.SVRCONN and select Configuration.
   
6. Select the Edit button.
   
7. Select SSL and in the SSL CipherSpec field, check that the value is ANY_TLS12_OR_HIGHER. This is not a list, so if you want to choose another cipher spec, please refer to the IBM MQ documentation for Enabling CipherSpecs
   
8. Click Save
9. Repeat the above for the CLOUD.APP.SVRCONN channel.
10. Now refresh the queue manager SSL Security if you have altered any channel above:
    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.

    The Cipher spec is now configured.

Using IBM MQ Explorer to alter the channels

1. Refer to Connect to your queue manager using MQ Explorer and perform the steps to connect to IBM MQ

2. In the IBM MQ Explorer - Navigator:

   1. Navigate to Queue Managers, expand your queue manager and click on Channels.
   2. In the Channels panel, double click on CLOUD.ADMIN.SVRCONN.
   3. In the CLOUD.ADMIN.SVRCONN properties panel, select SSL.
   4. In the SSL Cipher Spec: field, make sure a cipher spec is selected (ANY_TLS12_OR_HIGHER).
   5. Click Apply and then OK.
3. Repeat the above for the channel CLOUD.APP.SVRCONN

   

4. If you have altered the cipher spec for any channel, refresh the security. Under Queue Managers, right-click on the queue manager and select Security > Refresh SSL.

5. This completes enabling TLS encryption on the IBM MQ channels. If you no longer need the IBM MQ Explorer, you can disconnect the connection to queue manager by right clicking on queue manager and selecting Disconnect.

Create a Keystore file

To enable the client process to trust the queue manager, you must download the public certificate that will be presented by the queue manager.

Download the public certificate

The following steps can be used to download the public certificate and create that keystore.

1. Click on the Key store tab, and identify the certificate that is marked as "In use: Queue manager" (by default this is qmgrcert_yyyymm).
   

Create a Keystore file in PKCS12 format

1. Create a client key store using the runmqakm tool.

   $ runmqakm -keydb -create -db key.kdb -pw <your password> -type pkcs12 -expire 0 -stash
   
   $ # In some operating systems you may have to update the file permissions to make the keystore readable
   chmod +rw key.kdb

2. Import the queue manager certificate into the key store (this is the qmgrcert you downloaded from the IBM MQ as a Service user interface earlier).

   runmqakm -cert -add -db key.kdb -file qmgrcert_yyyymm.pem -label qmgrcert -stashed -type pkcs12 -format ascii

3. Check your certificates have been added.

   runmqakm -cert -list -db key.kdb

   Note: The type parameter above is pkcs12. Some samples suggest using kdb, but the resulting key.kdb is not readable by keytool, so for this exercise pkcs12 is preferred.

Create a Keystore file in JKS format on Windows and Linux®

Create a jks key store and copy the public part of queue manager certificate chain into it.

1. Create a client key store using the ikeycmd tool.

   $ ikeycmd -keydb -create -db key.jks -pw <your password> -type jks -expire 0 -stash 
   
   $ # In some operating systems you may have to update the file permissions to make the keystore readable
   chmod +rw key.jks

2. Import the queue manager certificate into the key store (this is the qmgrcert you downloaded from the IBM MQ as a Service user interface earlier).

   $ ikeycmd -cert -add -db key.jks -file qmgrcert_yyyymm.pem -label qmgrcert -pw <your password>

3. Check your certificates have been added.

   $ ikeycmd -cert -list -db key.jks

Create a Keystore file in JKS format on macOS

Create a jks key store and copy the public part of queue manager certificate chain into it.

1. Create a client key store and import the certificate.

   $ keytool -importcert -file qmgrcert_yyyymm.pem  -alias qmgrcert  -keystore key.jks -storepass <your password>

2. Check your certificates have been added.

   $ keytool -list -keystore key.jks -storepass <your password>

Next steps

Securing Administration

The next step is to configure the client end of the communication to trust the queue manager certificate. Choose the administration tool that you would like to use and follow the appropriate instructions below.

• Securing remote administration using IBM MQ Explorer
• Securing remote administration using runmqsc

Securing Application Connections

The next step is to configure your application connection so that it is uses TLS encryption when connecting to the queue manager.

• Securing application connections in C MQI and JMS programs