Summary

Scenario

You have an IBM MQ queue manager. An application is putting messages to a queue. Another application gets these messages from the queue.

Objective

You want to encrypt sensitive messages in the queue such as those containing Personally Identifiable Information (PII) or financial transactions.

IBM MQ Administrators, such as engineers working on the system, should not be able to read these messages from the queue to enforce confidentiality and governance.

Applications authenticated as the sender (putter apps) must encrypt the messages before putting them in the queue, while applications authenticated as the receiver (getter app) are the only party able to retrieve and decrypt this information.

Example

You have a messaging app that allows individuals to communicate with each other, using IBM MQ.

The following three personas will be used throughout this tutorial:

• Alice, the message sender
• Bob, the message receiver
• James, the IBM MQ Administrator

Alice can send a message containing PII to Bob that only he can read, which James cannot decrypt.

Solution

Advanced Messaging Security (AMS) is an MQ feature which performs this encryption.

The authenticated sender (Alice) encrypts the messages before putting them in the queue. Only the authenticated receiver (Bob) is able to decrypt them upon reception.

AMS is then enforced by default to avoid human error. You cannot forget to encrypt a message.

Instructions

Pre-requisites

If you want to create the entire end-to-end demo solution as described above from scratch, you can simply follow the instructions below.

You will need:

• A Red Hat OpenShift cluster version 4.10 or later (required for IBM MQ operator v2.0.0 [ref])
• On your local machine:
  • OpenShift oc CLI, logged into your cluster
  • Docker CLI (can be downloaded with Docker Desktop)
  • Maven for building the applications
  • Java for compiling and running the applications
  • A copy of the mq-ams-tutorial demo repository from GitHub

The instructions below are broken into sections, so if you instead want to use this tutorial as the basis for adding to an existing scenario (e.g. you already have an IBM MQ queue manager and want to add AMS) you can just choose the relative sections to follow.

IBM MQ with AMS on OpenShift

Setup LDAP

Install a development LDAP server that will manage user identities for the IBM MQ queue manager.

In order to authenticate applications to MQ, LDAP is required when running in a container as system users can't be used. An install script for LDAP has been provided in the 01-install-ldap directory.

./01-install-ldap/install.sh

Two LDAP users are defined in ldap-config.ldif, both members of the same group:

• mqwrite user for the putter app to put messages in the queue

dn: uid=mqwrite,ou=people,dc=ibm,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: mqwriteCN
sn: mqwriteSN
uid: mqwrite
userPassword: mqwrite

• mqread user for the Getter app to get messages from the queue

dn: uid=mqread,ou=people,dc=ibm,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: mqreadCN
sn: mqreadSN
uid: mqread
userPassword: mqread

• mqusers group which includes both mqwrite and mqread users

dn: cn=mqusers,ou=groups,dc=ibm,dc=com
objectClass: groupOfUniqueNames
objectClass: top
cn: mqusers

Generate certificates

Generate a new self-signed Certificate Authority (CA), and use it to create certificates for the MQ queue manager and the JMS MQ client apps.

Certificates are used to secure the connection between the apps and the MQ Queue Manager. The queue manager will only accept connections from certified apps.

These certificates will be used locally by the apps and stored in OpenShift secrets to be used by MQ.

To generate certificates for MQ, update the variables at the top of the generate.sh script before running it:

# Certificate information - Edit these variables to suit your project
export ORGANISATION=acmeinc
export COUNTRY=GB
export LOCALITY=Hursley
export STATE=Hampshire

./02-cert-generation/generate.sh

This script will create a 02-cert-generation/certs directory where the following files will be stored:

• ams-ca files - with the CA used to sign all certs in the tutorial demo
• ams-client files - used by the JMS applications
• ams-mq-server files - used by the IBM MQ queue manager

Generate MQS keys

Generate MQS keys to authenticate MQ users and enable encryption.

Only one user is allowed to send and encrypt messages (Alice), while only one user is allowed to receive and decrypt messages (Bob).

AMS makes use of MQS keys to:

• Authenticate the user performing the get/put action on the queue
• Encrypt messages with Alice's MQS key such that they can only be decrypted using Bob's MQS key

./03-mqs-keys/install-keys.sh

Setup IBM MQ on OpenShift

Create and configure a queue manager with AMS using IBM MQ OpenShift operator.

In order to deploy the IBM MQ operator on Red Hat OpenShift and deploy a Queue Manager with AMS, follow the steps below.

This tutorial assumes that you will be following the instructions on an OpenShift cluster where the MQ operator has not already been installed. Please read the instructions carefully if you already have a version of the operator installed.

1. To deploy the IBM MQ operator v2.0.0 on your cluster, run the deploy-operator.sh script.

   Warning: Please note that if you already have an existing MQ Operator on your cluster, this script may introduce errors. If you do not want to run the script, you can install the IBM MQ operator manually by running oc apply -f 04-openshift/resources/catalogsource.yaml and going into the OperatorHub in the OpenShift web console. Make sure you install version 2.0.0 or later.

   ./04-openshift/deploy-operator.sh

   

2. To set an IBM_ENTITLEMENT_KEY environment variable, get your key from the IBM Container Library and run:

   export IBM_ENTITLEMENT_KEY=<your-ibm-entitlement-key>

3. To deploy the queue manager on OpenShift, run the deploy-qmgr.sh script. This script will configure the queue manager to use LDAP, AMS, trust the JMS app certificates and recognise Alice and Bob keys.

   ./04-openshift/deploy-qmgr.sh

   

The main resources being deployed to OpenShift are the following:

• ibm-operator-catalog catalogsource: the IBM OpenShift operator catalogue where you can find the IBM MQ operator
• ibm-mq subscription: the subscription to IBM MQ operator to install it onto your cluster
• ibm-entitlement-key pull secret: IBM entitled registry key
• mq-server-tls secret: to store your generated certificates
• mq-ca-tls secret: to store your generated certificates
• mq-app-route route: used to put and get messages
• qmgr-setup config-map: defines the behaviour of the queue manager, including channels, queues, authentication, permissions and security
• ams-qmgr queuemanager: requires a few other resources that will be deployed automatically, including a service, a service account, the route to the web console…

After running the scripts you will have the following MQ setup running on OpenShift:

• IBM MQ Operator v2.0.0
• AMSQMGR Queue Manager v9.3.0.0-r1
  • AMS.QLOCAL queue
  • AMS.SVRCONN channel
  • Web console enabled
  • Trust your JMS application (certificates)
  • Only allows Alice to write and encrypt messages (MQS key)
  • Only allows Bob to read and decrypt messages (MQS key)
  • Using LDAP for authentication:
    • mqwrite user (putter app) can:
      • Connect to the queue manager
      • Access the channel
      • Write to the queue (put messages)
    • mqread user (getter app) can:
      • Connect to the queue manager
      • Access the channel
      • Read from the queue (get messages)

JMS applications

Setup the JMS apps

Compile the JMS Putter and Getter applications.

In order to build the JMS application that can send and receive encrypted messages from the queue, through authenticating as Alice or Bob, follow the steps below.

To start with, you will need to give all the information and credentials about your MQ instance to the apps. The simplest way to do so is to download a CCDT file locally from the MQ web console and make sure the apps are reading from it.

1. Login to the MQ web console using the following commands. Please be aware that the web console takes some time to become available after deploying the queue manager.

   1. Get the url:

      oc get queuemanager ams-qmgr -n ams-mq -ojsonpath='{.status.adminUiUrl}'

   2. If prompted, select IBM provided credentials

      

   3. Get the password for the admin username:

      oc -n ibm-common-services get secret platform-auth-idp-credentials -ojsonpath='{.data.admin_password}' | base64 --decode

      

2. Download the CCDT file for your MQ instance running on OpenShift

   1. From the homepage, go to Download connection files

      

   2. Select the following values:

      • Queue Manager: AMSQMGR
      • Channel: AMS.SVRCONN
      • Cipher: leave as default

      

   3. Leave Connections as default

      

   4. Download the CCDT file locally

      

3. Update the path to your CCDT file in the mq-config.properties file.

   # Absolute path to the CCDT file
   ccdt_location = <local-path-to-ccdt-file>

4. To build the JMS client apps with Maven, run the build.sh script

   ./05-mq-jms-app/build.sh

Run the JMS apps

Send encrypted messages and receive decrypted messsages as authenticated users, using the JMS applications.

1. Run the runPut.sh script to authenticate as Alice and write encrypted messages to the queue. The script will:

   • Update the path stored in the MQS_KEYSTORE_CONF environment variable to refer to Alice MQS folder (03-ams-keys/keys/alice/)
   • Run the putter app locally. The app puts a message containing a timestamp in the queue every 2 seconds.

   ./runPut.sh

2. Run the runGet.sh script to authenticate as Bob and read decrypted messages from the queue. The script will:

   • Update the path stored in the MQS_KEYSTORE_CONF environment variable to refer to Bob MQS folder (03-ams-keys/keys/bob/)
   • Run the Getter app locally. The app gets all the messages from the queue.

   ./runGet.sh

Since the messages are now encrypted, James the MQ Administrator will not be able to read them from the MQ Console or MQ CLI. He can see information about the queue such as the number of messages but not the messages themselves. You can check this feature by login in the MQ console (instructions listed in step 1).