Supplying the key repository password for an IBM MQ MQI client on AIX, Linux, and Windows

As the key repository contains sensitive information, it is secured with a password. To be able to access the key repository contents to perform TLS operations, IBM® MQ must be able to retrieve the key repository password.

IBM MQ provides four mechanisms to supply the key repository password to a IBM MQ MQI client:

The KeyRepoPassword fields of MQSCO
The MQKEYRPWD environment variable
The SSLKeyRepositoryPassword attribute of the client configuration file
The key repository stash file

If you do not use a key repository stash file, you can supply the key repository password as a plain text string, or a string that is encrypted by using the IBM MQ password protection system. For more information about the methods of protecting the key repository password, see Encrypting key repository passwords on AIX, Linux, and Windows.

The KeyRepoPassword fields of MQSCO

To supply a key repository password by using the MQSCO structure, you must use a combination of the following three variable string fields:

KeyRepoPasswordLength: The length of the password.
KeyRepoPasswordPtr: A pointer to the location in memory that contains the password.
KeyRepoPasswordOffset: The location of the password in memory, represented as number of bytes from the start of the MQSCO structure.

Note: You can supply only one of KeyRepoPasswordPtr or KeyRepoPasswordOffset.

For example:


char * pwd = "passw0rd";
MQSCO  SslConnOptions = {MQSCO_DEFAULT};

SslConnOptions.KeyRepoPasswordPtr = pwd;
SslConnOptions.KeyRepoPasswordLength = (MQLONG)strlen(SslConnOptions.KeyRepoPasswordPtr);
SslConnOptions.Version = MQSCO_VERSION_6;

Attention: If you supply the password by using this method, encrypt the password before it is supplied to the IBM MQ client application. For more information, see Encrypting the key repository password.

For more information about the MQCSO structure, see MQSCO - SSL/TLS configuration options.

The `MQKEYRPWD` environment variable

If a key repository password is not supplied to the client by using the MQSCO structure, you can specify the key repository password by using the MQKEYRPWD environment variable. For example:

export MQKEYRPWD=passw0rd

set MQKEYRPWD=passw0rd

where passw0rd is your password.

Attention: If you supply the password by using this method, encrypt the password before you set the value of the environment variable. For more information, see Encrypting the key repository password.

The SSLKeyRepositoryPassword attribute of the client configuration file

If a key repository password is not supplied to the client by using one of the other methods, you can specify the key repository password by using the SSLKeyRepositoryPassword attribute in the SSL stanza of the client configuration file. For example:


SSL:
    SSLKeyRepositoryPassword=passw0rd

Attention: If you supply the password by using this method, encrypt the password before setting the value of the SSLKeyRepositoryPassword attribute. For more information, see Encrypting the key repository password.

Ford more information about the SSL stanza of the client configuration file, see SSL stanza of the client configuration file.

The key repository stash file

If the key repository password is not supplied to the client by using one of the other methods, IBM MQ assumes that a stash file exists in the same directory as the key repository. The stash file has the same stem name as the key repository, but has the .sth extension.

A key repository stash file is created at the same time as the key repository, or later, using a separate runmqakm command.

Attention: The format of the stash file is specific to IBM MQ's cryptographic provider GSKit, and is not available on platforms that use a different cryptographic provider.

To create a stash file when the key repository is created, specify the -stash parameter. For example:

runmqakm -keydb -create -db key.kdb -pw passw0rd -stash

where passw0rd is the key repository password.

To create a stash file later, run the following command:

runmqakm -keydb -stashpw -db key.kdb -pw passw0rd

where passw0rd is the key repository password.

Encrypting the key repository password

If you supply the key repository password by using any method other than a stash file, encrypt the password by using the IBM MQ password protection system. To encrypt the password, run the runmqicred command. Enter the key repository password when prompted. The command outputs the encrypted password. The encrypted password can be supplied to the IBM MQ MQI client instead of the plain text password by using any of the methods described.

An encryption key, which is known as the initial key, is used to encrypt the password. When you encrypt the password, use a unique initial key to securely protect the password. To supply your own initial key, use the -sf parameter to the runmqicred command. If you do not supply an initial key, the default key is used.

For more information, see runmqicred (protect IBM MQ client passwords).

If you supply your own initial key when the key repository password is encrypted, and provide the encrypted password to the IBM MQ MQI client, you must also ensure that you supply the same initial key to the IBM MQ MQI client. For more information about how to provide the initial key to an IBM MQ MQI client, see Supplying an initial key for an IBM MQ MQI client on AIX, Linux, and Windows.