Using openssl s_client with IBM MQ
This blog post covers some of the ways that you can use the tool openssl s_client for some of your IBM MQ TLS (Transport Layer Security) needs. This blog assumes you have a general understanding of working with IBM MQ TLS and also the IBM MQ CERTLABL functionality. If not, it might be helpful to first review these sections in the MQ manual to gain some more context.
What is openssl s_client?
Openssl is an open source toolkit for Transport Layer Security (TLS) and Secure Socket Layer (SSL). The Linux distributions I work with come with it already installed. There are also Openssl downloads for Windows that are easy to download and set up that you can find on the internet. You can use Openssl by running the command openssl. The s_client option of the openssl command allows you to act as a TLS client and perform a TLS handshake with a TLS server. From an IBM MQ channel standpoint, an encrypted CLNTCONN channel would act as a TLS client and an encrypted SVRCONN channel would act as a TLS server. When the encrypted CLNTCONN channel connects to the encrypted SRVCONN channel, a TLS handshake is performed and a TLS connection is established.
Using openssl s_client with IBM MQ
The openssl s_client command can be a helpful tool when working with IBM MQ TLS.
For example, if you wanted to get the personal certificate of a remote queue manager that is on server1 and listening on port 1414 (maybe because you want to check its expiry date), you can run the following command:
openssl s_client -connect server1:1414
The output would normally be a lot of data, that would include near the top of the output the personal certificate that the queue manager is using in a PEM format. The PEM format starts with “BEGIN CERTIFICATE” and ends with “END CERTIFICATE”. You could then place the PEM format of this certificate in a file called cert.pem and use an openssl command like the following to read the contents.
openssl x509 -in cert.pem -noout -text
Another helpful piece of data in the openssl s_client output is a list of all the signer certs that this remote queue manager is trusting using the -showcerts option. This data can be helpful in debugging certain types of TLS issues.
openssl s_client -connect server1:1414 -showcerts
The above usage of openssl s_client is straight forward and was easy to use prior to IBM MQ v8. This is because prior to IBM MQ v8, a queue manager named QM1 would only reference one personal certificate in its keystore (e.g. a certificate with the label ibmwebspheremqqm1 on Linux). However, at IBM MQ v8 the CERTLABL functionality was added which allows there to be more than one personal certificate in the queue manager keystore that can be referenced by an IBM MQ queue manager. This CERTLABL change made things more complex when using openssl s_client with IBM MQ.
Using openssl s_client with IBM MQ and CERTLABL
So how do you use openssl s_client when interacting with an IBM MQ queue manager that is v8 or higher and could be using a CERTLABL configuration that allows there to be multiple personal certificates in use for this queue manager? This is done by using the -servername option of openssl s_client and providing the channel name that we are using to interact with this queue manager in the -servername option. However, the channel name needs a special format described in the following IBM support document.
https://www.ibm.com/support/pages/node/544699
There is also a Unix script at the bottom of this blog that is an aid to do this channel name to servername translation.
If our channel name was CLUS.TLS.SERVER, this channel name would translate to the TLS extension servername of clus2e-tls2e-server.chl.mq.ibm.com. We would then use the following openssl s_client command to interact with an IBM MQ v8 queue manager that is on server1 and listening on port 1414:
openssl s_client -connect server1:1414 -servername clus2e-tls2e-server.chl.mq.ibm.com
Things Still Aren’t That Simple
However, there are still nuances with CERTLABL that you need to be aware of. For example, the CERTLABL value on a channel definition is not used if the remote end is a Java or JMS client (NOTE: This Java/JMS CERTLABL restriction was removed at MQ 9.2 LTS). CERTLABL on the channel definition is also ignored if the remote queue manager is at a version lower than v8. You need to familiarize yourself with the CERTLABL functionality and its nuances in the MQ manual before you can effectively use openssl s_client on a v8 or higher queue manager to retrieve the correct personal certificate.
A simplified option when working with a v8 or higher queue manager might be to use the openssl s_client command twice, with and without the -servername option. If both ways return the same personal certificate, then you should feel confident that you have the correct personal certificate that queue manager will use for your specific scenario.
Conclusion
This blog post explains how you can use the openssl s_client command for some of your IBM MQ TLS needs. It also discusses the complexities that were added with CERTLABL, and how it can make it more difficult to use openssl s_client against an IBM MQ v8 or higher queue managers to obtain the correct personal certificate for your given scenario. Also, below is a Linux script that you might find helpful in doing the channel name to TLS extension servername translation.
#!/bin/bash
# script expects one command line argument for the channel name to translate to a TLS extension servername
str=$1
suffix=".chl.mq.ibm.com"
for (( i = 0; i < ${#str}; ++i)); do
c1="${str:$i:1}"
c2=`echo $c1 | sed 's/A/a/;s/B/b/;s/C/c/;s/D/d/;s/E/e/;s/F/f/;s/G/g/;s/H/h/;s/I/i/;s/J/j/;s/K/k/;s/L/l/;s/M/m/;s/N/n/;s/O/o/;s/P/p/;s/Q/q/;s/R/r/;s/S/s/;s/T/t/;s/U/u/;s/V/v/;s/W/w/;s/X/x/;s/Y/y/;s/Z/z/'`
if [ $c1 = $c2 ]; then
c2=`echo $c1 | sed 's/a/61-/;s/b/62-/;s/c/63-/;s/d/64-/;s/e/65-/;s/f/66-/;s/g/67-/;s/h/68-/;s/i/69-/;s/j/6a-/;s/k/6b-/;s/l/6c-/;s/m/6d-/;s/n/6e-/;s/o/6f-/;s/p/70-/;s/q/71-/;s/r/72-/;s/s/73-/;s/t/74-/;s/u/75-/;s/v/76-/;s/w/77-/;s/x/78-/;s/y/79-/;s/z/7a-/'`
fi
if [ $c1 = $c2 ]; then
c2=`echo $c1 | sed 's/%/25-/;s/\./2e-/;s/\//2f-/;s/_/5f-/'`
fi
if [ $c1 = $c2 ]; then
c2=`echo $c1 | sed 's/-/2d-/'`
fi
hold=$hold$c2
done
echo $hold$suffix