MQ

The TLS configuration for a .NET application running on Linux varies to that of a .NET application running on Windows.This blog intends to provide a basic way of configuring TLS for a .NET application running on Linux.

The managed MQ .NET client uses the Microsoft .NET system classes to implement TLS secure socket protocols. The Microsoft System.Net.SecuritySslStream class operates as a stream over connected TCP sockets and sends and receives data over that socket connection.

On Windows, .NET uses SCHANNEL, and on Linux® .NET uses OpenSSL for SSL Communications.The behavior of .NET application, including exception messages and error codes may therefore change depending on which platform it is run.

There are few subtle differences in how a .NET Core SSL connectivity works on window to that of on Linux, as there is a difference in the underlying classes that are used i.e SCHANNEL on Windows & OpenSSL on linux.

Couple of differences that have been identified are:

1. OpenSSL doesn't allow the connection to be established if the certificate is created using a smaller keysize.
2. OpenSSL doesn't allow the connection to be established if the certificate is created using an MD5 signature algorithm.

Following are the steps that can be used for configuring a MQ .NET Client and the Queue Manager so that a secure connection can be established between the client and the server.This example uses CA certificate.

Creating Certificates

1. Creating CA Certificates
   1. Create a Key Repository for the CA   runmqckm -keydb -create -db myCA.kdb -type cms
   2. Create your self-signed CA Certificate runmqckm -cert -create -db myCA.kdb -type cms -label "myCAcertificate" -dn "CN=myCAName,O=myOrganisation,OU=myDepartment,L=myLocation,C=IN" -expire 1000 -size 4096 -sig_alg SHA256WithRSA -ca true
   3. Extract the CA Certificate  runmqckm -cert -extract -db myCA.kdb -type cms -label "myCAcertificate" -target myCAcertfile.cer -format ascii
2. Creating Queue Manager Certificates
   1. Create a Key Repository for the Queue Manager Certificate runmqckm -keydb -create -db myqmgr.kdb -type cms -stash
   2. Generate a certificate request file for the queue manager,along with a private key runmqckm -certreq -create -db myqmgr.kdb -type cms -dn "CN=QMNAME,O=IBM,OU=WMQ,L=BNG,C=IN" -label "ibmwebspheremqmyqmgr" -file myqmgr.req -sig_alg SHA256WithRSA -size 4096
   3. Sign the Queue Manager certificate with CA runmqckm -cert -sign -db myCA.kdb -label "myCAcertificate" -expire 365 -format ascii -file myqmgr.req -target myqmgr.cer
   4. Add the public certificate of the CA to the key repository of the queue manager runmqckm -cert -add -db myqmgr.kdb -type cms -file myCAcertfile.cer -label "theCAcert"
   5. Receive the certificate (now signed by the CA) into the queue manager’s key repository: runmqckm -cert -receive -db myqmgr.kdb -type cms -file myqmgr.cer
   6. Set the path name for Queue Manager's key repository. We will be using a Queue Manager by name 'myqmgr'. The &KDB_PATH& refers to the path where the myqmgr.kdb has been created.
   7. Create and configure a Queue Manager for the SSL connectivity
      
      1. crtmqm myqmr
      2. strmqm myqmgr
      3. runmqsc myqmgr
         1. ALTER QMGR SSLKEYR('&KDB_PATH&\myqmgr')
         2. DEFINE CHANNEL(DOTNET.SVRCONN) CHLTYPE(SVRCONN) TRPTYPE(TCP)
            SSLCAUTH(REQUIRED) SSLCIPH('ANY_TLS12_OR_HIGHER')
         3. DEFINE QL(Q1)
         4. DEFINE LISTENER(L1) TRPTYPE(TCP) PORT(1414)
         5. START LISTENER(L1)
         6. REFRESH SECURITY TYPE(SSL)
3. Create Client Certificates
   1. Creating a Key Repository for the Client Application runmqckm -keydb -create -db myapp.p12 -type pkcs12 -stash
   2. Create a Certificate Request runmqckm -certreq -create -db myapp.p12 -type pkcs12 -dn "CN=myAppName,O=IBM,OU=myDepartment,L=BNG,C=IN" -label   "ibmwebspheremqroot" -file myapp.req -size 4096 -sig_alg SHA256WithRSA
   3. Sign the application cert with the CA runmqckm -cert -sign -db myCA.kdb -label "myCAcertificate" -expire 365 -format ascii -file myapp.req -target myapp.cer
   4. Add the CA certificate to the key repository of the application runmqckm -cert -add -db myapp.p12 -type pkcs12 -file myCAcertfile.cer -label "theCAcert" 
   5. Receive the certificate (now signed by the CA) into the application’s key repository runmqckm -cert -receive -db myapp.p12 -type pkcs12 -file myapp.cer

Installing Client Certificates on Linux

On Linux it is not recommended to modify the Certificate keystore manually,hence it is recommended to use an application to install the certificates in the keystore.Following .NET program could be used to install certificates on Linux. The program has to be updated with appropriate keystore and password values. The sample code below uses the keystore "myapp.p12" and password used to create that keystore

            try
            {
                X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
                store.Open(OpenFlags.ReadWrite);
                X509Certificate2 certificate1 = new X509Certificate2("myapp.p12", "*****");
                //Create a collection and add two of the certificates.
                X509Certificate2Collection collection = new X509Certificate2Collection();
                collection.Add(certificate1);
                //Add certificates to the store.
                store.Add(certificate1);
                store.AddRange(collection);
                X509Certificate2Collection collection2 = new X509Certificate2Collection();
                collection2.Import("myapp.p12", "*****", X509KeyStorageFlags.PersistKeySet);
                foreach (X509Certificate2 cert in collection2)
                {
                    store.Add(cert);
                    Console.WriteLine("Certificate installed successfully");
                }
            }
            catch (Exception e)
            {
                throw e;
            }

When the above program is run the certificates gets installed into location ~/.dotnet/corefx/cryptography/x509stores/my/. Please note the path might vary based on the OS,and the certificates installed should be on top of the list in the keystore for the MQ .NET Client to pick them up.

.NET Core application on Linux uses openssl,hence the CA certificates have to be installed in the OpenSSL CA certs path. Hence copy the myCAcertfile.cer created in the above steps to path /etc/pki/ca-trust/source/anchors/ and run update-ca-trust command. Please note the the path of ca-trust varies according to OS.

Running the MQ .NET application

Run the MQ .NET client sample shipped with the product.The below command will try to connect to a Queue Manager with listener port 1414 and channel DOTNET.SVRCONN  running on machine by name "remotehost". You could modify the input parameters accordingly.

dotnet SimplePut.dll -q Q1 -k *USER -s TLS_RSA_WITH_AES_128_CBC_SHA256 -h remotehost -p 1414 -l DOTNET.SVRCONN