A TLS (Transport Layer Security) connection is a secure, encrypted channel of communication between two applications, most commonly a client and a web server. It works by encrypting data to protect it from being intercepted or tampered with by third parties and ensures data authenticity and integrity.
IBM MQ .NET and XMS .NET applications can be used to send or receive messages to or from a queue using a secure TLS network. This is what we call TLS connectivity. By using appropriate certificates and Queue Manager settings one can create a TLS connection to a MQ Queue Manager. IBM MQ .NET managed mode has supported TLS since MQ v8. However, the configuration process was somewhat complex and behaved differently on Windows and Linux.
With MQ v9.4.4, the process of configuring TLS in Managed MQ and XMS .NET has been simplified with the introduction of a new feature. Users can now use a custom path in the file system where they can keep their certificates in proper keystores, and MQ .library will read the details from the path instead of having to install the certificates in windows or linux keystores. Password to the keystore, which can either be in plain-text or in an encrypted format, need to be provided in the .NET application.
How TLS Works
To be able to initiate a TLS connection there are a few pre-requisites that need to be addressed, after which one can adjust the Queue Manager settings in MQ server, and finally run the .NET application. The certificates need to be from an authorized publisher (CA) if they are being used in a production environment. IBM MQ .NET supports TLS on both windows and linux.
The best way to understand what has changed in MQ v9.4.4 is to compare the TLS configuration in MQ .NET. This post will focus primarily on the new custom certificate path feature.
TLS Configuration until MQ v9.4.4
The TLS configuration process before 9.4.4 consists of a series of steps. Here is a breakdown of the process.
Get or create certificates for application and server : A proper TLS certificate is required to initiate a handshake that results in a secure connection. Users could create their own personal certificates for tests, however for production ready environments it is recommended to use certificates published by certificate authorities.
There are commands that are used to create self-signed certificates for testing.
Next, install the p12 certificates into windows or linux keystore on the client machine using a .NET application or using GUI for windows. Keep the kdb certificates along with p12 public part in the Queue Manager location. Configure the Queue Manager to accept TLS connections and finally run your .NET application.
Refer to the blog post for more details on the existing TLS configuration process, https://community.ibm.com/community/user/blogs/ram-subba-rao-chalamalasetti/2024/02/15/tlsssl-configuration-for-a-mq-net-application-on-l.
In this blog, we will discuss more about the new feature.
What’s New In MQ v9.4.4
The TLS configuration has an additional feature in MQ v9.4.4 for MQ and XMS .NET. This new feature allows users to keep the certificates anywhere in file system, and the .NET libraries will pick it up from the location and authenticate it for TLS handshake. In this process of authentication, the password to the keystore along with encryption key must be passed on in the .NET client application, either in plain-text format or in an encrypted format.
Users can use new properties to implement the feature, i.e. to set a custom path for certificates to establish the TLS connections.
For MQ .NET :
- A path to the keystore (.p12 file) by using the MQC.SSL_CERT_STORE_PROPERTY.
- A keystore access password by using the MQC.SSL_CERT_STORE_PASSWORD_PROPERTY, either in plain text or encrypted format.
- An optional encryption key file path by using the MQC.ENCRYPTION_KEY_PROPERTY to decrypt encrypted passwords.
For XMS .NET :
- A path to the keystore (.p12 file) by using the XMSC.WMQ_SSL_KEY_REPOSITORY.
- A keystore access password by using the XMSC.WMQ_SSL_KEY_REPOSITORY_PASSWORD, either in plain text or encrypted form.
- An optional encryption key file path by using the XMSC.WMQ_ENCRYPTION_KEY to decrypt encrypted passwords.
The encryption feature is also provided by IBM, in the form of a new tool called rundotnetcred.
TLS Setup: Step-by-Step (New Method)
On client machine
For example :
Using Plain-text password
-k C:\temp\myapp.p12 -pa 123456
Using encrypted password
-k C:\temp\myapp.p12 -pa <DOTNET>2!ucDLjoLITqxfCOkiwrJIMA==!6vO3vUHLTWTSwzGRGguNDg== -e <Location to the encryption key>
,where -k is location of the keystore and -pa is the password to the keystore, and -e is the encryption key that was used to encrypt the password
On MQ server machine
- Keep the QM certificate bunch in the Queue Manager default location in MQ server
- Activate TLS on the Queue manager, by setting the appropriate cipherspec in channel, the path to the Qm certificate, and by setting SSL authentication as required.
- Do a refresh security
Once the setup is complete, run the .NET client application, and you should be able to connect to the QM using TLS if the certificate you are using is valid, and the password to the keystore is correctly provided.
Encryption is applied to the plain-text password of the TLS keystore, and only if enhanced security is required. This is done using a tool called rundotnetcred. It is present in <MQ installation>/bin directory on windows and <MQ installation>/lib64 directory on linux.
IBM MQ and XMS .NET supports AES 128 and 256 encryptions.
Running the .NET application
Run a MQ .NET sample shipped with the product, with a slight modification by adding the encryption key property (as mentioned above) in the application.
The below commands will connect to a Queue Q1 in a Queue Manager with listener port 1414, channel CH1, running on a machine with hostname "remotehost". You can modify the input parameters accordingly.
Using Plain-text Password options
-q Q1 -h remotehost -l CH1 -p 1415 -k C:\temp\myapp.p12 -pa 123456 -s TLS_RSA_WITH_AES_128_GCM_SHA256
,where -k is location of the keystore, -pa is the password to the keystore, and -s is the cipherspec algorithm
Using Encrypted Password options
-q Q1 -h remotehost -l CH1 -p 1415 -k C:\temp\myapp.p12 -pa <DOTNET>2!ucDLjoLITqxfCOkiwrJIMA==!6vO3vUHLTWTSwzGRGguNDg== -e C:\temp\eKey
,where -k is location of the keystore and -pa is the password to the keystore, and -e is the encryption key that was used to encrypt the password, and -s is the cipherspec algorithm
Password Encryption with rundotnetcred
Password encryption is required if users want enhanced security while using the custom path feature for TLS connectivity. Plain-text as well as encrypted passwords can be used for access to keystores. In order to encrypt a plain-text password use the rundotnetcred tool.
rundotnetcred -p <Plaintext-pass> -sf <Encryptionkey-filepath>
,where p is the plain text password, and sf is the path to an encryption key file
Encryption key is a 128 or a 256 bit unique key that can be provided as an optional parameter to encrypt the plain-text password. The same encryption key however needs to be provided to the MQ/XMS .NET client application as command line arguments.
Important :- If users do not provide an encryption key to the rundotnetcred tool, it uses an internal default key for encryption. And in such cases, no value for encryption key should be provided to the MQ/XMS .NET client application as well, as MQ libraries would use the default key to decrypt the password internally.
IBM MQ and XMS .NET supports AES 128 and 256 key encryption.
The output looks something like this :
<DOTNET>2!iS9ccKTjsZ35SbqHQzQ3yKfodnNeId5UnWreJ99v+/0=!SGzPyIJnWaFacu5h
which is a combination of various strings:
- An eyecatcher
- The algorithm type
- A separator
- The Base64-sfncoded encrypted password
- A separator
- The vector (IV)
The output of the tool is an AES encrypted password, which now becomes the value of SSL_CERT_STORE_PASSWORD_PROPERTY in MQ .NET and WMQ_SSL_KEY_REPOSITORY_PASSWORD in XMS .NET applications respectively.
If encryption key was used initially in rundotnetcred tool, then the same string becomes the value of ENCRYPTION_KEY_PROPERTY in MQ .NET and WMQ_ENCRYPTION_KEY in XMS .NET applications respectively.
See also,
Custom path for certificates in .NET for TLS connectivity using plain text or encrypted passwords
Custom path for certificates in XMS .NET for TLS connectivity using plain text or encrypted passwords