Enabling TLS security for MQ channels in MQ on Cloud

Using the MQ on Cloud service console to gather credentials and certificates

1. Open the MQ on Cloud service console and locate your queue manager.

2. Gather the admin user's credentials When you first select the Administration tab for your queue manager, your user will be given permissions as the administrator. 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).

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.

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"
     }
   ]
   }
   

The following sections describe how to check that the channels already have TLS configured, and if not configure them to apply TLS security.

Using 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 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 MQ Explorer to alter the channels

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

2. In the 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 pannel, 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 MQ channels. If you no longer need the MQ Explorer, you can disconnect the connection to queue manager by right clicking on queue manager and selecting Disconnect.

Using runmqsc to alter the channels

1. Refer to Connect to your queue manager using runmqsc and perform the steps to connect to your MQ on Cloud queue manager. Do not exit the runmqsc command shell as is will be used in steps below.

2. If your queue manager is 9.2.1 r1 or lower, run following commands to configure the channels:

     ALTER CHANNEL(CLOUD.ADMIN.SVRCONN) CHLTYPE(SVRCONN) SSLCAUTH(OPTIONAL) SSLCIPH(ANY_TLS12_OR_HIGHER)
     ALTER CHANNEL(CLOUD.APP.SVRCONN) CHLTYPE(SVRCONN) SSLCAUTH(OPTIONAL) SSLCIPH(ANY_TLS12_OR_HIGHER)
     REFRESH SECURITY TYPE(SSL)
     end
   

3. This completes enabling TLS encryption on the MQ channels. If you no longer need the runmqsc cli, you can exit now.

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

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

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 MQ on Cloud 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
   

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 MQ on Cloud 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 Mac OSX

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>
   

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.

• Configuring security for remote administration using IBM MQ Explorer
• Configuring security for remote administration using runmqsc CLI

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.

• Connect securely from MQI C & JMS application