This blog post is going to cover how to set up TLS secured client channels when using MO71 to connect to your queue managers. Before I start, I just want to say up front that there is nothing special about how you do this. MO71 is a ‘C’ language MQI application and so setting up TLS for MO71 is just the same as setting it up for the IBM supplied ‘C’ language sample amqsputc as an example. If you know how to do that, then you know how to set it up for MO71.
In order to have TLS secured connectivity between MO71 and your queue manager, your queue manager must have a certificate, hopefully not a self-signed certificate; and you, the MO71 user, must also have a certificate identifying you. It is likely that this certificate identifying you will be used for connectivity from various different tools, so it does not need to be specific to MO71. This blog post is not going to cover setting up the queue manager certificate as that has been amply covered in IBM Docs. What you need at your MO71 machine is a signed certificate identifying you, and a copy of the CA certificate that signed the queue manager’s certificate. It is possible that you have several of the latter item depending on how your queue managers are setup. One hopes that you have many less of these than the number of queue managers you need to manage.
Key Database File
MO71 is a ‘C’ language MQI application. This means that the IBM MQ Client code expects it to use a KDB file with a matching named stashed file. Unlike Java programs, you do not provide the password to the certificate store (KDB file) anywhere, the IBM MQ Client code finds the stash file that contains the password due to the fact that it has the same name as the KDB file. Here is my set of files:-
Directory of C:\MQGem 06/07/2021 16:43 88 MQGemClient.crl 06/07/2021 16:43 20,088 MQGemClient.kdb 06/07/2021 16:43 88 MQGemClient.rdb 06/07/2021 16:43 193 MQGemClient.sth 4 File(s) 20,457 bytes
Later you will see when configuring MO71 that you use the name up to, but not including, the file extension. The IBM MQ Client code can construct the name of the key repository and password stash file by appending the “.kdb” and “.sth” file extensions respectively.
If you don’t already have a KDB file supplied for your use, you should create one now.
Step 1: Create a KDB file
IBM MQ supplies tools for you to create the files you need. In this case we show examples of using the command line tool runmqakm. There is also a GUI tool that can do the same job. Here is the command to create your KDB file. In my example, the KDB file (and accompanying stash file etc) will be created in the C:\MQGem directory, using names MQGemClient.* – you may wish to change this. In addition, you probably want a stronger password too!
runmqakm -keydb -create -db C:\MQGem\MQGemClient.kdb -pw passw0rd -type cms -stash
If you want, you can use the runmqakm tool to create a password for you:-
runmqakm -random -create -length 16 -strong
The KDB file, once created, is the place to put the various certificates you need. As mentioned above, you’ll need to have the CA certificate that signed your queue manager(s) certificates. This is so that the certificates coming from the queue managers at connection time can be validated by the IBM MQ Client as part of the TLS handshake.
If you have one or more files containing the CA certs to allow you to validate connections to your queue manager(s), add them to your KDB now. If you only have a single certificate file (a PKCS#12 file) that also contains the CA certs, skip Step 2.
Step 2: Add CA certificates to KDB
Here is the command to add a CA certificate to your KDB. As before, you are likely using a different location in your file system for the KDB file. Note that I am using the -stashed parameter from now on, so I never have to type in the password again. The label you use when you add a CA certificate doesn’t matter. Just make it something that is helpful in remembering what this certificate is. In my example MQGemProdCA is the label I have used for the production environment CA certificate.
runmqakm -cert -add -db C:\MQGem\MQGemClient.kdb -stashed -label MQGemProdCA -file MQGemProdCA.arm -format ascii -trust enable
Finally you need to have a certificate identifying you, the user of MO71. You may have been given a file already containing your signed certificate, and have to add that to your KDB, or you may need to generate a certificate request, get it signed by your company CA, and then when you get it back, receive it into the same KDB where you created the request. Choose either Step 3a or 3b below depending on how your company does this.
DO THIS: Step 3a: Add PKCS#12 private certificate into KDB
This special certificate type is one that contains both your certificate and the private key for the certificate. It is very important to keep the private key safe, so when transporting this around in a PKCS#12 file, this particular type of file has a password. Other files that only contain certificates without private keys don’t have passwords.
Here is the command to add a PKCS#12 certificate file to your KDB. This command will also add the CA certificates that are in the file. Note that I am using the -stashed parameter for the KDB password, so I never have to type in the password again. The password on this command is the one that goes with the PKCS#12 file you have been given.
runmqakm -cert -import -file MoragCertificate.p12 -type pkcs12 -pw pkcs12passw0rd -target c:\MQGem\MQGemClient.kdb -stashed
OR THIS: Step 3b: Create a Certificate Request
To make a certificate request, issue the following command, using the KDB file that you just created.
runmqakm -certreq -create -db C:\MQGem\MQGemClient.kdb -stashed -label MQAdminProd -dn "CN=Morag Hughson,OU=Prod,O=MQGem Software" -file Clnt_Prod_Request.csr
Now send the certificate request file off to the CA that signs certificates for your environment. When you receive the signed certificate file back from them, receive it into the same KDB as before with the following command.
runmqakm -cert -receive -db C:\MQGem\MQGemClient.kdb -stashed -file Clnt_Prod_Signed.arm
As a final check that everything got added ok, list the contents of your KDB with the following command.
runmqakm -cert -list all -db C:\MQGem\MQGemClient.kdb -stashed
You should see output something like this. There should be at least one trusted certificate (shown with a !) and at least one personal certificate (shown with a -). You will need the label of the personal certificate when you come to configure MO71 in a moment, so remember that.
5724-H72 (C) Copyright IBM Corp. 1994, 2020. Certificates found * default, - personal, ! trusted, # secret key ! MQGemProdCA - MQAdminProd
Now that you have all the certificates put in place, you’re going to need to create a TLS-secured server-connection (SVRCONN) channel on the queue manager if you don’t already have one in place.
Step 4: Create TLS-secured SVRCONN channel
Here’s an example MQSC command to define such a channel. The name you use for your channel may well be different. Whatever it is, remember it for the next step.
Your company may choose to use a different CipherSpec (the SSLCIPH) parameter. I have chosen to use the more recently introduced ANY_TLS12. If you can’t use one of the “ANY” values then you will need to make sure that you use the same value that is in your SVRCONN when you come to configure MO71 in the next step.
DEFINE CHANNEL(MQGEM.SVRCONN.TLS) CHLTYPE(SVRCONN) TRPTYPE(TCP) SSLCIPH(ANY_TLS12) SSLCAUTH(REQUIRED)
Now you are ready to configure MO71 to connect securely to your queue manager. It is worth saying here that you can, if you want to, set up MO71 just as you would set up the IBM supplied sample amqsputc. You could create a CCDT, and use the MQSSLKEYR and MQCERTLABL environment variables.
However, here we are going to configure MO71 by filing in the various fields in the Client configuration on the Location Dialog.
If you already have a location in MO71 for this queue manager that you just need to change to use TLS now, skip Step 5 and just open up the location dialog for your existing location and click on thebutton to get to the Client Channel dialog.
Step 5: Add Location
Choose menu File>Add Location…
In the location dialog that appears, fill in a name for the Location; the Queue Manager name; put this location in a group if you are using them; check the Client box and you will find that thebutton is now enabled to press. Pressing it will open up the client configuration dialog.
Step 6: Client Configuration Dialog
In the Client Channel Definition dialog, make sure that you have the correct channel name, you may have to change it if you previously were connecting without TLS. Ensure you have a connection name filled in if you are making a new location here. If you are altering an existing one, there should be no change required as the same listening port is used for both clear and TLS connections. Choose a Cipher Spec that either matches what you have on the queue manager SVRCONN, or uses the same protocol that is requested. I have ANY_TLS12 on the SVRCONN so I have chosen a TLS1.2 Cipher Spec. You can see which Cipher Specs use which protocol on this handy page in IBM Docs.
Once you have selected a Cipher Spec, the dialog will show you the other SSL/TLS related fields. Fill in the Key Repository remembering not to include the extension of the file as discussed earlier. And fill in the Certificate Label that you took note of earlier.
Now click on
Step 7: Test Connectivity
The easiest way to test your newly configured connectivity is from the Location dialog. If you just added it as a new location, you will have to reopen the location dialog by right-clicking on the queue manager in the list on the main window and choosing Open Location.
Use thebutton first. Look in the Status bar at the bottom for any error messages and if you get an error message, use the button to quickly bring up the client error log for more details about the error – remember to scroll to the bottom.
If thebutton changes to and the top of the dialog now says “[Connected]” then you have successfully connected MO71 over TLS and you are good to go! From now on all TCP/IP traffic over this client connection is secure.
It is hoped that this post will help you set up TLS-secured connectivity between the MO71 program and your queue manager. Remember that the same KDB file and certificates will also work with the IBM-supplied samples such as amqsputc. If you have any issues, it may be helpful to try things out with that very simple sample first. It is also good advice if you get validation problems to change the SVRCONN channel to use SSLCAUTH(OPTIONAL) and get it working that way first. Once it does then go back to SSLCAUTH(REQUIRED) knowing that the problem is that you are either not sending, or the queue manager is not validating, the client side certificate.
There are a few considerations about multiple environments, e.g. Test vs Production, that I would like to cover, but this post is already quite long, so I will write another post about that and link it in here once complete.
If you have situations where you are trying to set up TLS-secured connectivity for MO71 that are not covered in this post, please do get in touch, either in a comment below, or through any of the usual channels (see About page).