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 iKeyman user interface, or by using the iKeycmd 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, 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 iKeyman or iKeycmd 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 iKeyman or iKeycmd must be a member of the mqm group. For an IBM MQ MQI client, if you run iKeyman or iKeycmd 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 iKeyman or iKeycmd Version 7.0, new key databases are automatically populated with a set of pre-defined certificate authority (CA) certificates. In iKeyman or iKeycmd Version 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: Because of this change in behavior for GSKit Version 8.0 that results in CA certificates no longer being automatically added to the repository, you must manually add your preferred CA certificates. This change of behavior provides you with more granular control over the CA certificates used. See Add default CA certificates into an empty key repository on UNIX, Linux, and Windows with GSKit Version 8.0.

Procedure

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

To create a key database by using the iKeyman 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 iKeyman 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, you 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:
- On UNIX, Linux, and Windows systems:
```
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: