Securing remote administration using runmqsc

Before you begin

Configuring runmqsc to use standard ("one way") TLS connections

Download or create a JSON CCDT file that describes the queue manager you want to connect to

You can download a JSON CCDT from the queue manager details page by clicking on the Connection information button and then selecting the JSON CCDT format. Note that the downloaded JSON CCDT does not contain the cipher specification that you associated with the channel, so you have to include that manually by adding a transmissionSecurity definition for each channel as shown in the example below.

Alternatively you can simply copy the example template provided here and update the host, port, queueManager and channel values to match your queue manager.

{
  "channel": [
  {
    "name": "CLOUD.ADMIN.SVRCONN",
    "clientConnection": {
      "connection": [
      {
      "host": "qm1-1234.qm.us-south.mq.appdomain.cloud",
      "port": 31500
      }
      ],
      "queueManager": "QM1"
    },
    "transmissionSecurity": {
      "cipherSpecification": "ANY_TLS12_OR_HIGHER"
    },
    "type": "clientConnection"
  }
  ]
}

Configure the necessary environment variables for the runmqsc environment

You configure environment variables to instruct the runmqsc client to use the JSON CCDT to obtain the queue manager connection details, which includes the name of the channel cipher spec that we defined in the previous step.

1. Open a command prompt window and navigate to the IBM MQ bin directory of your installation. The location of this will depend on your operating system, for example:

   Operating System	File location
   Linux® full IBM MQ installation	/var/mqm/bin
   Windows	C:\Program Files\IBM\MQ\bin
   Linux/macOS, using the client installation	~/mytoolkit/IBM-MQ-Toolkit-Mac-x64-9.1.2.0/bin

2. Set the MQCCDTURL environment variable to instruct the runmqsc client to read the JSON CCDT, the MQCCDTURL variable is a URL pointing to the JSON CCDT file.
   • MQCCCDTURL is the full file path from the system root to the ccdt file.

     # Linux/MacOS
     export MQCCDTURL=file:///Users/myuser/connection_info_ccdt.json    
     unset MQSERVER
     
     # Windows
     set MQCCDTURL=file:///c:/temp/connection_info_ccdt.json    
     set MQSERVER=        

     Note: You MUST NOT have the MQSERVER variable set, otherwise that will take precedence over the settings from the JSON CCDT
   • There are two different ways of specifying your CCDT file location - if MQCCDTURL does not work for you, try setting MQCHLTAB and MQCHLLIB as described below.

     MQCHLLIB is the full path from the system root to the directory which holds the ccdt file.

     export MQCHLLIB=/path/to/ccdt
     set MQCHLLIB=c:\path\to\ccdt

     MQCHLTAB is the filename of the ccdt file.

     export MQCHLTAB=connection_info_ccdt.json
     set MQCHLTAB=connection_info_ccdt.json

3. Set the MQSSLKEYR environment variable to allow the runmqsc client to trust the TLS certificate presented by the queue manager

   The MQSSLKEYR variable must be set to the full path from the system root to a keystore file that contains the TLS certificate presented by the queue manager.

   Note that the .kdb suffix of the file must NOT be included in the MQSSLKEYR value. So, for a key store named key.kdb, specify just key.

   # Linux/MacOS
   export MQSSLKEYR=/Users/myuser/key
   
   # Windows
   set MQSSLKEYR=c:\temp\key

Execute the runmqsc command to connect to the queue manager

Now that we have set up the necessary environment we can execute the runmqsc command to connect to the queue manager.

Configuring runmqsc to use mutual ('two way') TLS connections

The following steps describe how to extend the instructions above to configure mutual TLS connectivity between the runmqsc client and the queue manager.

In mutual TLS scenarios the client (for example,. runmqsc) presents a client certificate to the queue manager, and the queue manager must be configured to trust that incoming client certificate.

1. Generate a TLS client certificate that will identify the runmqsc client:

   In some organizations TLS client certificates are generated for you by a central certificate authority (CA). For the purposes of this example we will generate our own self-signed client certificate.

   # Generate a new private key and public certificate for the client
   # (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 -addext "extendedKeyUsage = clientAuth"
   
   # Combine the private key and public certificate into a single file
   cat clientKey.pem > clientCombined.pem
   cat clientCert.pem >> clientCombined.pem

2. Add the newly generated client certificate to the local keystore file:

   Import the combined client key/cert into the keystore file, making a note of the label that you use.

   $ runmqakm -cert -add -db key.kdb -file clientCombined.pem -label runmqsc -stashed -type pkcs12 -format ascii

3. Configure the queue manager to trust the client certificate:

   • Import the public part of the client certificate by navigating to the queue manager details page in the IBM MQ as a Service service console user interface, and selecting the Trust store tab
   • Click the Import certificate button, and select the file containing the public part of the client certificate, for example clientCert.pem
   • Click Next and pick a label for the certificate (it does not have to be the same label as in the client keystore file), then click
   • After the certificate has been uploaded you are requested to refresh the queue manager SSL security configuration which you can do using IBM MQ Console, SaveIBM MQ Explorer or runmqsc as described in Administering a queue manager using IBM MQ Explorer and the runmqsc command line.

4. Configure the queue manager channel to require mutual TLS:

   • The TLS mode for a channel is controlled by the SSL Authentication attribute of the channel, which must be set to Required to enable mutual TLS. You can set the attribute using IBM MQ Console or IBM MQ Explorer via the UI, or if you are using runmqsc then you must set the attribute SSLCAUTH to REQUIRED.

5. Configure runmqsc to present the client certificate when it connects to the queue manager:

   • Set the MQCERTLABL environment variable to the label of the client certificate in the local keystore file, and then you can execute the runmqsc command to connect to the queue manager, which this time will be configured using mutual TLS authentication.

     export MQCERTLABL=runmqsc
     runmqsc -c -u mqusername QM1

Next steps

If you want to connect applications to a queue manager that has TLS enabled on the channels then you can follow the instructions in the following topic;

• Securing application connections in C MQI and JMS programs