Configure TLS on queue managers

After starting the IBM Key Management (iKeyman) GUI, we can use it to manage TLS certificates. We can also authenticate certificates by using either Certificate Revocation Lists or OCSP authentication.


Before starting

For more information on how to start the iKeyman GUI, see Starting the IBM Key Management GUI .


This task introduces the commands that we use to work with TLS on an IBM MQ client. For more information, see Securing and Set up IBM MQ MQI client security.

Complete any of the following tasks:
  1. Create the queue manager key repository
  2. Change the queue manager key repository location
  3. Authenticate certificates using Certificate Revocation Lists
  4. Authenticate certificates using OCSP authentication
  5. Configure cryptographic hardware


Procedure

  • [OPTION 1] Create the queue manager key repository

    The key repository is where certificates used by the queue manager are stored. On Windows, Linux, and UNIX platforms, the key repository is known as the key database file.

    Before we can store the queue manager certificates in the key repository, we must ensure that a key database file exists in this location.

    1. Find the location of the queue manager key repository. This is specified in the queue manager's Key Repository attribute.
    2. For to create the key database file, do this using the iKeyman GUI. For more information, see Starting the IBM Key Management GUI.
    3. In the iKeyman GUI, ensure that the queue manager key repository contains all the Certificate Authority (CA) certificates that might be required to validate certificates that are received from other queue managers.

  • [OPTION 2] Change the queue manager key repository location

    In certain circumstances you might want to change the key repository location; for example, to use a single location that is shared by all queue managers on one operating system.

    To change a queue manager key repository location:

    1. Change the key repository location in the queue manager properties:
      1. Open IBM MQ Explorer and expand the Queue Managers folder.
      2. Right-click the queue manager, then click Properties.
      3. On the SSL property page, edit the path in the Key repository field to point to your chosen directory.
      4. In the warning dialog, click Yes.

    2. Transfer the queue manager personal certificates to the new location using the iKeyman GUI. For more information, see Securing.

  • [OPTION 3] Authenticate certificates using Certificate Revocation Lists

    Certification Authorities (CAs) can revoke certificates that are no longer trusted by publishing them in a Certification Revocation List (CRL). When a certificate is received by a queue manager or an IBM MQ MQI client, it can be checked against the CRL to ensure that it has not been revoked. CRL checking is not mandatory for TLS-enabled messaging to be achieved, but is recommended to ensure the trustworthiness of user certificates.

    To set up a connection to an LDAP CRL server, complete the following steps:

    1. In IBM MQ Explorer, expand the queue manager.
    2. Create an authentication information object of type CRL LDAP. For more information, see Create and configure queue managers and objects.
    3. Repeat the previous step to create as many CRL LDAP authentication information objects as you need.
    4. Create a namelist and add to the namelist the names of the authentication information objects that you created in Steps 2 and 3. For more information, see Create and configure queue managers and objects.
    5. Right-click the queue manager, then click Properties.
    6. On the SSL page, in the CRL Namelist field, type the name of the namelist that you created in Step 4.
    7. Click OK.

    The certificates that the queue manager receives can now be authenticated against the CRL held on the LDAP server.

    We can add to the namelist up to 10 connections to alternative LDAP servers to ensure continuity of service if one or more LDAP servers are inaccessible.

  • [OPTION 4] Authenticate certificates using OCSP authentication

    On UNIX and Windows, IBM MQ TLS support checks for revoked certificates using OCSP (Online Certificate Status Protocol) or using CRLs and ARLs on LDAP (Lightweight Directory Access Protocol) servers. OCSP is the preferred method. IBM MQ classes for Java and IBM MQ classes for JMS cannot use the OCSP information in a client channel definition table file. However, we can configure OCSP as described in Revoked certificates and OCSP.

    IBM i and z/OS do not support OCSP checking, but they do allow the generation of client channel definition tables (CCDTs) containing OCSP information.

    For more information about CCDTs and OCSP, see Client channel definition table.

    To set up a connection to an OCSP server, complete the following steps.

    1. In IBM MQ Explorer, expand the queue manager.
    2. Create an authentication information object of type OCSP. For more information, see Create and configure queue managers and objects.
    3. Repeat the previous step to create as many OCSP authentication information objects as we need.
    4. Create a namelist and add to the namelist the names of the OCSP authentication information objects that you created in Steps 2 and 3. For more information, see Create and configure queue managers and objects.
    5. Right-click the queue manager, then click Properties.
    6. On the SSL page, in the Revocation namelist field, type the name of the namelist that you created in Step 4.
    7. Click OK.

    The certificates that the queue manager receives are authenticated against the OCSP responder.

    The queue manager writes OCSP information to the CCDT.

    Only one OCSP object can be added to the namelist because the socket library can only use one OCSP responder URL at a time.

  • [OPTION 5] Configure cryptographic hardware

    IBM MQ can support cryptographic hardware, and the queue manager must be configured accordingly.

    1. Start IBM MQ Explorer.
    2. In the Navigator view, right-click the queue manager, then click Properties. The Properties dialog opens.
    3. On the SSL page, click Configure. The Cryptographic Hardware Settings dialog opens.
    4. In the Cryptographic Hardware Settings dialog, enter the path to the PKCS #11 driver, and the token label, the token password, and the symmetric cipher setting.

      All supported cryptographic cards now use PKCS #11, so ignore references to the Rainbow Cryptoswift or nCipher nFast cards.

    5. Click OK.

    The queue manager is now configured to use the cryptographic hardware.

    We can also work with certificates that are stored on PKCS #11 hardware using iKeyman.

    For more information, see Securing.

Parent topic: Securing channels with TLS


Related tasks


Related reference