Set up a key repository

 

An SSL connection requires a key repository at each end of the connection. Each WebSphere MQ queue manager and WebSphere MQ client must have access to a key repository. See The SSL key repository for more information.

On UNIX and Windows systems, digital certificates are stored in a key database file that is managed with iKeyman or IKEYCMD. These digital certificates have labels. A specific label associates a personal certificate with a queue manager or WebSphere MQ client. SSL uses that certificate for authentication purposes. On UNIX and Windows systems, WebSphere MQ uses the ibmwebspheremq prefix on a label to avoid confusion with certificates for other products. The prefix is followed by the name of the queue manager or WebSphere MQ client user logon ID, changed to lower case. Ensure that you specify the entire certificate label in lower case.

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

Note that key repositories should not be created on a file system that does not support file level locks, for example NFS version 2 on Linux.

Working with a key repository tells you 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 iKeyman or IKEYCMD 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 WebSphere MQ client, if you run iKeyman or IKEYCMD from a user ID different from that under which the client runs, alter the file permissions to enable the WebSphere MQ client to access the key database file at run time. For more information, refer to Accessing your key database file.

Use the following procedure to create a new key database file for either a queue manager or a WebSphere MQ client:

  1. Start the iKeyman GUI (using the gsk7ikm command on UNIX, or the strmqikm command on Windows).

  2. From the Key Database File menu, click New. The New window is displayed.

  3. Click Key database type and select CMS (Certificate Management System).

  4. 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 have specified a different stem name, replace key with your stem name but not change the .kdb.

  5. In the Location field, type the path, for example:

    • For a queue manager: /var/mqm/qmgrs/QM1/ssl (on UNIX) or C:\Program Files\IBM\WebSphere MQ\qmgrs\QM1\ssl (on Windows)

    • For a WebSphere MQ client: /var/mqm/ssl (on UNIX) or C:\mqm\ssl (on Windows)

  6. Click Open. The Password Prompt window displays.

  7. Type a password in the Password field, and type it again in the Confirm Password field.

  8. Select the Stash the password to a file check box.

    If you do not stash the password, attempts to start SSL channels fail because they cannot obtain the password required to access the key database file.

  9. Click OK. A window is displayed, confirming that the password is in file key.sth (unless you specified a different stem name).

  10. Click OK. The Signer Certificates window is displayed, containing a list of the CA certificates that are provided with iKeyman and pre-installed in the key database.

  11. Set the access permissions, as described in Accessing your key database file.

Use the following commands to create a new CMS key database file using IKEYCMD or GSKCapiCmd:

where:

-db filename is the fully qualified file name of a CMS key database, and must have a file extension of .kdb.
-pw password is the password for the CMS key database (for WebSphere MQ, this must be cms.
-type cms is the type of database.
-expire days is the expiration time in days of the database password. There is no default time for a database password: use the -expire option to set a database password expiration time explicitly.
-stash tells IKEYCMD or GSKCapiCmd to stash 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 have been FIPS 140-2 validated. If the ICC component does not initialize in FIPS mode, the gsk7capicmd 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 lower case character, one upper case 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 only occur a maximum of three times in a password.

  • A maximum of two consecutive characters in the password can be identical.

  • All characters described above are in the standard ASCII printable character set within the range from 0x20 to 0x7E inclusive.

For more information about CA certificates, refer to Digital certificates.

 

Parent topic:

Working with the Secure Sockets Layer (SSL) on UNIX and Windows systems


sy12150_