Example: Configuring TLS

This example deploys a queue manager into the Red Hat® OpenShift® Container Platform using the IBM® MQ Operator. One-way TLS communication is configured between a sample client and the queue manager. The example demonstrates successful configuration by putting and getting messages.

Before you begin

To complete this example, you must first have completed the following prerequisites:

Install the IBM MQ client, and add samp/bin and bin to your PATH. You need the runmqakm, amqsputc and amqsgetc applications, which can be installed as part of the IBM MQ client as follows:
- For Windows and Linux®: Install the IBM MQ redistributable client for your operating system from https://ibm.biz/mq92redistclients
- For Mac: Download and set up the IBM MQ MacOS Toolkit: https://developer.ibm.com/tutorials/mq-macos-dev/
Install the OpenSSL tool for your operating system.
Create a Red Hat OpenShift Container Platform (OCP) project/namespace for this example.
On the command line, log into the OCP cluster, and switch to the above namespace.
Ensure the IBM MQ Operator is installed and available in the above namespace.

About this task

This example provides a custom resource YAML defining a queue manager to be deployed into the Red Hat OpenShift Container Platform. It also details the additional steps required to deploy the queue manager with TLS enabled. Upon completion, putting and getting messages validates the queue manager is configured with TLS.

Create a TLS private key and certificates for the IBM MQ server

The following code examples show how to create a self-signed certificate for the queue manager, and how to add the certificate to a key database to act as the truststore for the client. If you already have a private key and certificate, you can use those instead.

Note that self-signed certificates should only be used for development purposes.

Create a self-signed private key and a public certificate in the current directory

Run the following command:

openssl req -newkey rsa:2048 -nodes -keyout tls.key -subj "/CN=localhost" -x509 -days 3650 -out tls.crt

Add the server public key to a client key database

The key database is used as the truststore for the client application.

Create the client key database:

runmqakm -keydb -create -db clientkey.kdb -pw password -type cms -stash

Add the previously generated public key to the client key database:

runmqakm -cert -add -db clientkey.kdb -label mqservercert -file tls.crt -format ascii -stashed

Configure TLS Certificates for Queue Manager deployment

So that your queue manager can reference and apply the key and certificate, create a Kubernetes TLS secret, referencing the files created above. When you do this, ensure you are in the namespace you created before you began this task.

oc create secret tls example-tls-secret --key="tls.key" --cert="tls.crt"

Create a config map containing MQSC commands

Create a Kubernetes config map containing the MQSC commands to create a new queue and a SVRCONN Channel, and to add a channel authentication record that allows access to the channel by blocking only those users called nobody.

Note that this approach should be used only for development purposes.

Ensure you are in the namespace you created earlier (see Before you begin), then enter the following YAML in the OCP UI, or using the command line.

apiVersion: v1
kind: ConfigMap
metadata:
  name: example-tls-configmap
data:
  tls.mqsc: |
    DEFINE QLOCAL('EXAMPLE.QUEUE') REPLACE 
    DEFINE CHANNEL(SECUREQMCHL) CHLTYPE(SVRCONN) TRPTYPE(TCP) SSLCAUTH(OPTIONAL) SSLCIPH('ANY_TLS12_OR_HIGHER')
    SET CHLAUTH(SECUREQMCHL) TYPE(BLOCKUSER) USERLIST('nobody') ACTION(ADD)

Create the required OCP route

Ensure you are in the namespace you created before you began this task, then enter the following YAML in the OCP UI, or using the command line.

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: example-tls-route
spec:
  host: secureqmchl.chl.mq.ibm.com
  to:
    kind: Service
    name: secureqm-ibm-mq
  port:
    targetPort: 1414
  tls:
    termination: passthrough

Note that the Red Hat OpenShift Container Platform Router uses SNI for routing requests to the IBM MQ queue manager. If you change the channel name specified in the MQSC in the config map created earlier, you also need to change the host field here, and in the CCDT file created later. For more information, see Configuring a Route to connect to a queue manager from outside a Red Hat OpenShift cluster.

Deploy the queue manager

Important: In this example we use the MQSNOAUT variable to disable authorization on the queue manager, which allows us to focus on the steps required to connect a client using TLS. This is not recommended in a production deployment of IBM MQ, because it causes any applications connecting to have full administrative powers, with no mechanism to lower the permissions for individual applications.

Create a new queue manager using the following custom resource YAML. Note that it references the config map and secret created earlier, as well as the MQSNOAUT variable.

Ensure you are in the namespace you created before you began this task, then enter the following YAML in the OCP UI, using the command line or using the IBM Cloud Pak® for Integration Platform Navigator. Check that the correct license is specified, and accept the license by changing false to true.

apiVersion: mq.ibm.com/v1beta1
kind: QueueManager
metadata:
  name: secureqm
spec:
  license:
    accept: false
    license: L-RJON-C7QG3S
    use: Production
  queueManager:
    name: SECUREQM
    mqsc:
    - configMap:
        name: example-tls-configmap
        items:
        - tls.mqsc
    storage:
      queueManager:
        type: ephemeral
  template:
    pod:
      containers:
        - env:
            - name: MQSNOAUT
              value: 'yes'
          name: qmgr
  version: 9.2.5.0-r3
  web:
    enabled: true
  pki:
    keys:
      - name: example
        secret:
          secretName: example-tls-secret
          items: 
          - tls.key
          - tls.crt

Confirm that the queue manager is running

The queue manager is now being deployed. Confirm it is in Running state before proceeding. For example:

oc get qmgr secureqm

Test the connection to the queue manager

To confirm the queue manager is configured for one-way TLS communication, use the amqsputc and amqsgetc sample applications:

Find the queue manager hostname

Use the following command to find the queue manager fully-qualified hostname for route secureqm-ibm-mq-qm:

oc get routes secureqm-ibm-mq-qm

Specify the queue manager details

Create a file CCDT.JSON that specifies the queue manager details. Replace the host value with the hostname from the previous step.

{
    "channel":
    [
        {
            "name": "SECUREQMCHL",
            "clientConnection":
            {
                "connection":
                [
                    {
                        "host": "<hostname from previous step>",
                        "port": 443
                    }
                ],
                "queueManager": "SECUREQM"
            },
            "transmissionSecurity":
            {
              "cipherSpecification": "ECDHE_RSA_AES_128_CBC_SHA256"
            },
            "type": "clientConnection"
        }
   ]
}

Export environment variables

Export the following environment variables, in the manner appropriate for your operating system. These variables will be read by amqsputc and amqsgetc.

Update the path to the files on your system:

export MQCCDTURL='<full path to file>/CCDT.JSON'
export MQSSLKEYR='<full path to file>/clientkey'

Put messages to the queue

Run the following command:

amqsputc EXAMPLE.QUEUE SECUREQM

If connection to the queue manager is successful, the following response is output:

target queue is EXAMPLE.QUEUE

Put several messages to the queue, by entering some text then pressing Enter each time.

To finish, press Enter twice.

Retrieve the messages from the queue

Run the following command:

amqsgetc EXAMPLE.QUEUE SECUREQM

The messages you added in the previous step have been consumed, and are output.

After a few seconds, the command exits.

Congratulations, you have successfully deployed a queue manager with TLS enabled, and shown that you can securely put and get messages to the queue manager from a client.