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

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

About this task

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.

The key database file name comprises a path and stem name:

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, you 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 Changing the key repository location for a queue manager on UNIX, Linux, and Windows for information about checking and specifying the key database file name. You 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, you 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 in IBM WebSphere® MQ 7.0, new key databases are automatically populated with a set of pre-defined certificate authority (CA) certificates. In strmqikm or runmqckm in IBM MQ 8.0, key databases are not automatically populated, making the initial setup more secure because you include only the CA certificates that you want, in your key database file.

Note: This change in behavior for IBM Global Security Kit (GSKit) 8.0 results in CA certificates no longer being automatically added to the repository. So you must manually add your preferred CA certificates. This change of behavior provides you with more granular control over the CA certificates used. See Adding default CA certificates into an empty key repository on UNIX, Linux, and Windows with GSKit 8.0.

You create the key database either by using the command line, or by using the strmqikm (iKeyman) user interface.

Note: If you 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.

Procedure

Create a key database by using the command line.

Run either of the following commands:
- Using runmqckm:
```
runmqckm -keydb -create -db filename -pw password -type cms -stash
```
- Using 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 IBM Crypto for C (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.

Alternatively, create a key database by using the strmqikm (iKeyman) user interface.

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.
Start the user interface by running the strmqikm command.
From the Key Database File menu, click New.
The New window opens.
Click Key database type and select CMS (Certificate Management System).
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, you must not change the .kdb extension.
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).
Click OK.
The Password Prompt window opens.
Type a password in the Password field, and type it again in the Confirm Password field.
Select the Stash the password to a file check box.

Note: If you do not stash the password, attempts to start TLS channels fail because they cannot obtain the password required to access the key database file.
Click OK.
The Personal Certificates window opens.
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.