Set up a key repository

 

You cannot run SSL channels from a WebSphere MQ installation that uses DCE security exits or the DCE name service.

A DCE-threaded WebSphere MQ client application cannot use SSL on AIX, Solaris, or HP-UX. TXSeries uses DCE threads, so it cannot run as a WebSphere MQ client that uses SSL on AIX, Solaris, or HP-UX. DCE threads are incompatible with the threads used by the WebSphere MQSSL support.

Before you run SSL on HP-UX, recompile and link the WebSphere MQ client applications using the C++ compiler.

On UNIX systems, you manage keys and digital certificates with the iKeyman key management tool, which you can run either as a GUI or from the command line:

Use the gsk6ikm command to start the iKeyman GUI.

Use the gsk6cmd command to perform tasks with the IKEYCMD command line interface.

See the WebSphere MQ System Administration Guide for a full description of the IKEYCMD command line interface.

Before you execute the gsk6ikm command to start the iKeyman GUI, ensure you are working on a machine that is able to run the X Window System and that you do the following: Set the DISPLAY environment variable, for example:

export DISPLAY=mypc:0

Set the JAVA_HOME environment variable:

Linux export JAVA_HOME=/opt/mqm/ssl/jre
Solaris export JAVA_HOME=/opt/mqm/ssl

If you are using Linux for zSeries, set the LD_PRELOAD environment variable: export LD_PRELOAD=/usr/lib/libstdc++-libc6.1-2.so.3

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

On UNIX systems, digital certificates are stored in a key database file that is managed with iKeyman.

Note:
These digital certificates have labels. A label associates a certificate with a queue manager or WebSphere MQ client. SSL uses that certificate for authentication purposes. On UNIX 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, folded 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:

  • For a queue manager, the default path, set when you create the queue manager, is /var/mqm/qmgrs/<queue_manager_name>/ssl and the default stem name is key. Optionally, you can choose the own path and stem name, but the extension must be .kdb.

  • For a WebSphere MQ client, there is no default path or stem name. Choose a key database file to which you can restrict access.

Working with a key repository tells you 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.

Notes:

  1. The user ID from which you run iKeyman must have write permission for the directory in which the key database file is created or updated.

  2. For a queue manager, the user ID from which you run iKeyman must be a member of the mqm group. For a WebSphere MQ client, if you run iKeyman from a user ID different from that under which the client runs, alter the permissions to enable the WebSphere MQ client to access the key database file at run time. For more information, refer to Accessing the 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. Execute the gsk6ikm command to start the iKeyman GUI.

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

  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 the stem name is key, leave this field unchanged. If you have specified a different stem name, replace key with the stem name but not change the .kdb.

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

    • For a queue manager: /var/mqm/qmgrs/PARIS/ssl

    • For a WebSphere MQ client: /var/mqm/ssl

  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.

    Note:
    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 displays, confirming that the password is in file key.sth (unless you specified a different stem name).

  10. Click OK. The Signer Certificates window displays, 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 the key database file.

Use the following command to create a new CMS key database file using IKEYCMD: 

gsk6cmd -keydb -create -db filename -pw password -type cms -expire days -stash

where:

-db filename is the fully qualified path name of a CMS key database.
-pw password is the password for the CMS key database.
-type cms is the type of database.
-expire days is the expiration time in days of the database password. The default is 60 days for a database password.
-stash tells IKEYCMD to stash the key database password to a file.

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

 

Accessing the key database file

When you create the key database file using iKeyman, the access permissions for the key database file are set to give access only to the user ID from which you used iKeyman.

The key database file is accessed by an MCA, so ensure that the user ID under which the MCA runs has permission to read both the key database file and the password stash file. MCAs usually run under the mqm user ID, which is in the mqm group. After you have created the queue manager key database file, work with the same user ID to add read permission for the mqm group, using the UNIX chmod command. For example: 

chmod g+r /var/mqm/qmgrs/PARIS/ssl/key.kdb"
 
chmod g+r /var/mqm/qmgrs/PARIS/ssl/key.sth

When you set up the key database file for a WebSphere MQ client, consider working with the user ID under which you run the WebSphere MQ client. This allows you to restrict access to that single user ID. When you need to grant access to a user ID in the same group, use the UNIX chmod command. For example: 

chmod g+r /var/mqm/ssl/key.kdb"
 
chmod g+r /var/mqm/ssl/key.sth

Avoid giving permission to user IDs that are in different groups. For more information, refer to Protecting WebSphere MQ client key repositories.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.