Set up a key repository on UNIX, Linux, and Windows

We can set up a key repository by the using strmqikm (iKeyman) GUI, or from the command line using runmqckm (iKeycmd) or runmqakm (GSKCapiCmd) commands.

A TLS connection requires a key repository at each end of the connection. Each IBM MQ queue manager and IBM MQ MQI client must have access to a key repository. For more information, see The SSL/TLS key repository.

On UNIX, Linux, and Windows systems, digital certificates are stored in a key database file that is managed by using the strmqikm user interface, or by using the runmqckm or runmqakm commands. These digital certificates have labels. A specific label associates a personal certificate with a queue manager or IBM MQ MQI client. TLS uses that certificate for authentication purposes. On UNIX, Linux, and Windows systems, IBM MQ uses either the value of the CERTLABL attribute, if it is set, or the default ibmwebspheremq with the name of the queue manager or IBM MQ MQI client user logon ID appended, all in lowercase. See Digital certificate labels for details.

• On UNIX and Linux systems, the default path for a queue manager (set when you created the queue manager) is /var/mqm/qmgrs/queue_manager_name/ssl.

  On Windows systems, the default path is MQ_INSTALLATION_PATH\Qmgrs\queue_manager_name\ssl, where MQ_INSTALLATION_PATH is the directory in which IBM MQ is installed. For example, C:\Program Files\IBM\MQ\Qmgrs\QM1\ssl.

  The default stem name is key. Optionally, we can choose your own path and stem name, but the extension must be .kdb.

  If you choose your own path or file name, set the permissions to the file to tightly control access to it.

• For an IBM MQ client, there is no default path or stem name. Tightly control access to this file. The extension must be .kdb.

Do not create key repositories on a file system that does not support file level locks, for example NFS version 2 on Linux systems.

See Change the key repository location for a queue manager on UNIX, Linux, and Windows for information about checking and specifying the key database file name. We can specify the key database file name either before or after creating the key database file.

The user ID from which you run the strmqikm or runmqckm commands must have write permission for the directory in which the key database file is created or updated. For a queue manager using the default ssl directory, the user ID from which you run strmqikm or runmqckm must be a member of the mqm group. For an IBM MQ MQI client, if you run strmqikm or runmqckm from a user ID different from that under which the client runs, we must alter the file permissions to enable the IBM MQ MQI client to access the key database file at run time. For more information, see Accessing and securing your key database files on Windows or Accessing and securing your key database files on UNIX and Linux systems.

In strmqikm or runmqckm Version 7.0, new key databases are automatically populated with a set of pre-defined certificate authority (CA) certificates. In strmqikm or runmqckm Version 8.0, key databases are not automatically populated, making the initial setup more secure because we include only the CA certificates that we want, in your key database file.

Procedure

Note: If we must manage TLS certificates in a way that is FIPS-compliant, use the runmqakm command. The strmqikm user interface does not provide a FIPS-compliant option.

• To create a key database by using the strmqikm user interface, complete the following steps:
  1. On UNIX and Linux systems, log in as the root user. On Windows systems, log in as Administrator or as a member of the MQM group.
  2. Start the user interface by running the strmqikm command.
  3. From the Key Database File menu, click New. The New window opens.
  4. Click Key database type and select CMS (Certificate Management System).
  5. In the File Name field, type a file name. This field already contains the text key.kdb. If your stem name is key, leave this field unchanged. If you specified a different stem name, replace key with your stem name. However, we must not change the .kdb extension.
  6. In the Location field, type the path. For example:
     • For a queue manager: /var/mqm/qmgrs/QM1/ssl (on UNIX and Linux systems) or C:\ProgramData\IBM\MQ\qmgrs\QM1\ssl (on Windows systems).

       The path must match the value of the SSLKeyRepository attribute of the queue manager.

     • For an IBM MQ client: /var/mqm/ssl (on UNIX and Linux systems) or C:\mqm\ssl (on Windows systems).

  7. Click OK. The Password Prompt window opens.
  8. Type a password in the Password field, and type it again in the Confirm Password field.
  9. Select the Stash the password to a file check box. Note: If we do not stash the password, attempts to start TLS channels fail because they cannot obtain the password required to access the key database file.
  10. Click OK. The Personal Certificates window opens.
  11. Set the access permissions as described in Accessing and securing your key database files on Windows or Accessing and securing your key database files on UNIX and Linux systems.

• To create a key database by using the command line, use either of the following commands:
  • Use runmqckm:

    runmqckm -keydb -create -db filename -pw password -type cms -stash
    

  • Use runmqakm:

    runmqakm -keydb -create -db filename -pw password -type cms
    -stash -fips -strong
    

  where:

  -db filename

  Specifies the fully qualified file name of a CMS key database, and must have a file extension of .kdb.

  -pw password

  Specifies the password for the CMS key database.

  -type cms

  Specifies the type of database. (For IBM MQ, it must be cms.)

  -stash

  Saves the key database password to a file.

  -fips

  Specifies that the command is run in FIPS mode. When in FIPS mode, the ICC component uses algorithms that are FIPS 140-2 validated. If the ICC component does not initialize in FIPS mode, the runmqakm command fails.

  -strong

  Checks that the password entered satisfies the minimum requirements for password strength. The minimum requirements for a password are as follows:

  • The password must be a minimum length of 14 characters.
  • The password must contain a minimum of one lowercase character, one uppercase character, and one digit or special character. Special characters include the asterisk (*), the dollar sign ($), the number sign (#), and the percent sign (%). A space is classified as a special character.
  • Each character can occur a maximum of three times in a password.
  • A maximum of two consecutive characters in the password can be identical.
  • All characters are in the standard ASCII printable character set, within the range 0x20 - 0x7E.

• Accessing and securing your key database files on Windows
  The key database files might not have appropriate access permissions. We must set appropriate access to these files.
• Accessing and securing your key database files on UNIX and Linux systems
  The key database files might not have appropriate access permissions. We must set appropriate access to these files.
• Adding default CA certificates into an empty key repository on UNIX, Linux, and Windows with GSKit Version 8.0
  Follow this procedure to add one or more of the default CA certificates to an empty key repository with GSKit version 8.

Parent topic: Work with SSL/TLS on UNIX, Linux, and Windows