[IBM i]

Supplying the key repository password for an IBM MQ MQI client on IBM i

Because 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:

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 IBM i.

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
or 
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 using the amqrsslc command line tool. To create the stash file, run the following command:
CALL PGM(QMQM/AMQRSSLC) PARM('-s' '/Path/Of/KeyDatabase/MyKey')
This command prompts you for the password to encrypt. The password is encrypted by the IBM MQ password protection system, with a default encryption key unless one is provided using the -sf parameter.

For more information, see IBM MQ SSL Client utility (amqrsslc) for IBM i and Encrypting 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 IBM i.