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

You can set up a key repository by using the iKeyman user interface, or by using the iKeycmd or runmqakm commands.

About this task

An SSL or TLS connection requires a key repository at each end of the connection. Each IBM® WebSphere® MQ queue manager and IBM WebSphere MQ MQI client must have access to a key repository. For more information, see The SSL or 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 WebSphere MQ MQI client. SSL and TLS use that certificate for authentication purposes. On UNIX, Linux, and Windows systems, IBM WebSphere MQ uses ibmwebspheremq as a label prefix to avoid confusion with certificates for other products. The prefix is followed by the name of the queue manager or IBM WebSphere MQ MQI client user logon ID, changed to lowercase. Ensure that you specify the entire certificate label in lowercase.

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 WebSphere MQ is installed. For example, C:\program files\IBM\WebSphere 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 a WebSphere 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 or Windows systems 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 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 a IBM WebSphere 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 WebSphere 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 Adding default CA certificates into an empty key repository on UNIX, Linux, and Windows systems with GSKit version 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:
- On UNIX, Linux, and Windows systems:
```
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 WebSphere MQ, it must be cms.)

-stash

Saves the key database password to a file.

-fips

Disables the use of the BSafe cryptographic library. Only the ICC component is used and this component must be successfully initialized 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.

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 iKeyman 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:\Program Files\IBM\WebSphere MQ\qmgrs\QM1\ssl (on Windows systems).
  The path must match the value of the SSLKeyRepository attribute of the queue manager.
- For an IBM WebSphere MQ client: /var/mqm/ssl (on UNIX and Linux systems) or C:\mqm\ssl (on Windows systems).
Click Open.
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 SSL or 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.