Configuring TLS for managed IBM MQ .NET

Configuring TLS for managed IBM® MQ .NET consists of creating the signer certificates, then configuring the server side, the client side, and the application program.

About this task

To configure TLS, you must first create the appropriate signer certificates. Signer certificates can be either self signed or certificates provided by a certificate authority. Although self-signed certificates can be used on a development, test or pre-production system, do not use them on a production system. On a production system, use certificates that you have obtained from a trusted external certificate authority (CA).

Procedure

  1. Create the signer certificates.
    1. To create self-signed certificates, use one of the following tools provided with IBM MQ :
      Use the strmqikm GUI, or use runmqckm or runmqakm from the command line. For more information on using these tools, see Using runmqckm, runmqakm, and strmqikm to manage digital certificates.
    2. To obtain certificates for the queue manager and clients from a certificate authority (CA), follow the instructions in Obtaining personal certificates from a certificate authority.
  2. Configure the server side.
    1. Configure TLS on the queue manager, using IBM Global Security Kit (GSKit), as described in Connecting a client to a queue manager securely.
    2. Set the SVRCONN channel TLS attributes:
      • Set SSLCAUTH to "REQUIRED/OPTIONAL".
      • Set SSLCIPH to an appropriate CipherSpec.
      For more information, seeEnabling TLS for the unmanaged .NET client.
  3. Configure the client side.
    1. Import the client certificates into the Windows certificate store (under the User/Computer account).
      IBM MQ .NET accesses client certificates from the Windows certificate store, therefore you must import your certificates into the Windows certificate store to establish a secure socket connection to IBM MQ . For more information about how to access the Windows keystore and import the client side certificates, see Import or export certificates and private keys.
    2. Supply the CertificateLabel as described in Connecting a client to a queue manager securely.
    3. If needed, edit the Windows Group Policy to set the CipherSpec, then, for the Windows Group Policy updates to take effect, restart the computer.
  4. Configure the application program.
    1. Set the MQEnvironment or the SSLCipherSpec value to denote the connection as a secured connection.
      The value that you specify is used to identify the protocol being used (TLS). The CipherSpec set should be one of the CipherSpecs of the supported SSLProtocol version and it can preferably be the same as the one specified in the Windows Group Policy. (The supported SSLProtocol version depends on the .NET framework used. The SSLProtocol version can be TLS 1.0, or TLS 1.2, depending on which version of the Microsoft .NET Framework you are using.)
      Note: If the CipherSpec value supplied by the application is not a CipherSpec known to IBM MQ, then the IBM MQ managed .NET client disregards it and negotiates the connection based on the Windows system's group policy.
    2. Set the SSLKeyRepository property to either "*SYSTEM" or "*USER".
    3. Optional: Set SSLPEERNAME to the distinguished name (DN) of the server certificate.
    4. Supply the CertificateLabel as described in Connecting a client to a queue manager securely.
    5. Set any further optional parameters that you require such as KeyResetCount, CertificationRevocationCheck, and enable FIPS.

Examples of how to set the TLS protocol and TLS key repository

For Base .NET, you can set the TLS protocol and TLS key repository through the MQEnvironment class as shown in the following example: 

MQEnvironment.SSLCipherSpec = "TLS_RSA_WITH_AES_128_CBC_SHA256";
MQEnvironment.SSLKeyRepository = "*USER";

MQEnvironment.properties.Add(MQC.SSL_CIPHER_SPEC_PROPERTY, "TLS_RSA_WITH_AES_128_CBC_SHA256")
Alternatively, you can set the TLS protocol and TLS key repository by supplying a hashtable as part of the MQQueueManager constructor as shown in the following example. 

Hashtable properties = new Hashtable();
properties.Add(MQC.SSL_CERT_STORE_PROPERTY, sslKeyRepository);
properties.Add(MQC.SSL_CIPHER_SPEC_PROPERTY, "TLS_RSA_WITH_AES_128_CBC_SHA256")

What to do next

For more information about getting started with developing IBM MQ .NET managed TLS applications, seeWriting a simple application.