Protecting passwords in IBM MQ component configuration files

To use certain features of IBM® MQ, passwords might have to be supplied either directly to IBM MQ or in configuration files that the feature reads. From IBM MQ 9.2.0, a password protection system is implemented that protects passwords in these configuration files.

Passwords in configuration files must be encrypted. The following list explains the common terminology that is used for each component:

Initial key

The encryption key that is used to protect the password.

For each component listed, supply a unique initial key that is used to protect passwords stored in the configuration of that component. The same initial key must also be made available to the component for the password to be decrypted.

Most components require the initial key to be supplied in a file. The initial key file must:

Contain a single line of at least one character.
Be adequately protected by using the operating system permissions.

There are no requirements about the length of the initial key or the characters that can be specified. However, for adequate security, you should specify an initial key that is at least 16 characters long. For example, your initial key file might contain:

Th1sIs@n3Ncypt|onK$y

Default initial key

The default encryption key used, if you do not supply an initial key when you are encrypting data. However, you should not use the default initial key as it does not adequately protect the encrypted data .

Plain text string

The string that is encrypted, commonly a password.

Encrypted password string

A string that contains the encrypted password in a format that IBM MQ understands.

Important: Encrypted password strings that you generated for use with one component cannot be copied to the configuration file of another component for use. Each password for each component must be protected by using the component-specific utility.

Details of how to protect passwords for each component of IBM MQ that supports password protection are listed in the following sections:

Advanced Message Security
Managed File Transfer
IBM MQ Internet Pass-Thru
IBM MQ Bridge to blockchain
IBM MQ Bridge to Salesforce
IBM MQ clients that use cryptographic hardware
IBM MQ queue manager
IBM MQ C client applications
Native HA configurations
IBM MQ queue manager (AuthToken stanza in the qm.ini file)

Advanced Message Security

Advanced Message Security (AMS) Java clients require access to a keystore that contains private keys to protect message.

[MQ 9.3.0 Jun 2022] Advanced Message Security (AMS) MQI clients or queue managers that are configured to perform MCA interception might require access to PKCS#11 cryptographic hardware, or PEM files that contain private keys to protect messages.

To access these files, a password must be provided in the AMS configuration file that is called a keystore.conf. Use the runamscred command to protect the sensitive information contained in the keystore.conf file. For example,

runamscred -f <keystore configuration file>

The runamscred command protects sensitive parameters within the file that is specified, by using the -f flag.

Two runamscred programs are added to the IBM MQ installation:

An MQI runamscred program located in <IBM MQ installation root>/bin
A Java runamscred program located in <IBM MQ installation root>/java/bin

Attention: To ensure compatibility,

Use the Java runamscred program to protect configuration files to be used with Java AMS clients and the MQI runamscred program to protect configuration files to be used with the MQI AMS clients.
Verify that all the necessary sensitive information is protected after you run runamscred.
Supply the protected file as normal to AMS enabled applications.

To override or provide the initial key file to use at run time of AMS applications, or when you are protecting a keystore configuration file by using runamscred, use one of the following four mechanisms, in order of priority:

-sf parameter (runamscred only)
MQS_AMSCRED_KEYFILE environment variable
amscred.keyfile parameter in the keystore.conf configuration file
Default initial key file if none of the previous options are specified.
Attention: Do not use the default initial key.

Before IBM MQ 9.2, a different password protection system was used to protect passwords in AMS Java configuration files.

By default, the runamscred program protects passwords by using the new system. This means that new configuration files are not compatible with older versions of AMS Java. To protect configuration files with the old password protection system, use the -sp 0 flag.

Managed File Transfer

Managed File Transfer (MFT) stores credentials that are required to access queue managers or other resources in several XML property files:

MQMFTCredentials.xml - Credentials for connecting to agent, coordination, and command queue managers and passwords for connecting to keystores for secure communications.
ProtocolBridgeCredentials.xml - Credentials for connecting to Protocol Servers, such as FTP/SFTP/FTPS.
ConnectDirectCredentials.xml - Credentials for Connect:Direct® agent to connect to a Connect:Direct node.

For more information, see Encrypting stored credentials in MFT.

To protect sensitive information stored in these files, use the fteObfuscate command within the file that is specified, by using the -f flag, for example:

fteObfuscate -f <File to protect>

To provide an initial key file to use during the protection of your MFT configurations, use the -sf flag:

fteObfuscate -f <File to protect> -sf <initial key file>

If you do not provide an initial key, a default key is used to protect the sensitive information, although you should not use this option.

Attention:

Verify that all the necessary sensitive information is protected after you run fteObfuscate.
Supply the protected file as normal to MFT.

At run time, provide the initial key file to use through the following three mechanisms, in order of priority, these are:

By using a Java system property.
- Before IBM MQ 9.3.1 and IBM MQ 9.3.0 Fix Pack 10, the name of this Java system property was misspelled in the product code as com.ibm.wqmfte.cred.keyfile. From IBM MQ 9.3.1 and IBM MQ 9.3.0 Fix Pack 10, the spelling of the property name is corrected to be com.ibm.wmqfte.cred.keyfile. Managed File Transfer uses both versions of the Java system property when it checks whether a user specified a file that contains the initial key to be used for encrypting and decrypting credentials. This allows the use the correct spelling of the property name, while maintaining compatibility with an earlier version with the old misspelled name. Note that if both Java system properties are set, then the value of the correctly spelled property com.ibm.wmqfte.cred.keyfile is used.
- Before IBM MQ 9.3.1 and IBM MQ 9.3.0 Fix Pack 10, use the property com.ibm.wqmfte.cred.keyfile.
In the agent, logger, commands, and coordination property files.
In the installation.properties file.

Before IBM MQ 9.2, a different credential protection system was used to protect credentials in the MFT configuration files.

By default, fteObfuscate protects credentials by using the new system; this means configuration files are not compatible with older versions of MFT.

To protect configuration files with the old credentials protection system, use the -sp 0 parameter.

IBM MQ Internet Pass-Thru

The IBM MQ Internet Pass-Thru (MQIPT) configuration file can contain passwords to access various resources and the MQIPT administration password.

You can protect these passwords by using the mqiptPW command that is supplied with MQIPT.

mqiptPW

To protect a password with a specific initial key, supply the -sf flag:

mqiptPW -sf <intial key file>

For more information, see Specifying the password encryption key.

If you do not provide an initial key, a default key is used to protect the sensitive information, although you should not use this option.

mqiptPW prompts you to securely enter a password to protect, and returns a string that needs to be copied into the MQIPT configuration file.

At run time, provide the initial key file to use through the following four mechanisms. In order of priority, these are:

Through the -sf parameter when MQIPT is started.
In the MQS_MQIPTCRED_KEYFILE environment variable.
In the com.ibm.mq.ipt.cred.keyfile Java property.
In a file named mqipt_cred.key in the MQIPT home directory, that is the directory that contains the MQIPT configuration and log files, and others.

Before IBM MQ 9.2, a different credential protection system was used to protect credentials in the MQIPT configuration files.

By default, mqiptPW protects credentials that use the new system; this means that configuration files are not compatible with older versions of MQIPT.

To protect keystore passwords that use the old credentials protection system, use the mqiptPW command syntax that is supported in versions earlier than IBM MQ 9.2.

IBM MQ Bridge to blockchain

Bridge to blockchain configurations are stored in files that can be generated with the runmqbcb command. When you run this command, you are asked to securely provide passwords and a location of an initial key file to use.

To override what initial key file to use during runtime or configuration mode use the -sf flag. For example, generate a configuration with a specific initial key file:

runmqbcb -o <output file> -sf <initial key file>

Or to use a specific initial key file during runtime:

runmqbcb -f <config file> -sf <initial key file>

Before IBM MQ 9.2, a different credential protection system was used to protect credentials in the Bridge to blockchain configuration files.

By default, runmqbcb protects credentials by using the new system, this means configuration files are not compatible with older versions of the Bridge to blockchain.

To protect configuration files with the old credentials protection system, use the -sp 0 flag.

Important:

The IBM MQ Bridge to blockchain is deprecated across all releases from November 22 2022 (see US Announcement letter 222-341). Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities available with IBM Cloud Pak® for Integration.
For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product at IBM MQ 9.3.2.

IBM MQ Bridge to Salesforce

Bridge to Salesforce configurations are stored in files that can be generated with the runmqsfb command. While running this command, you are asked to securely provide passwords and a location of an initial key file to use.

To override what initial key file to use during runtime or configuration mode use the -sf flag. For example, to generate a configuration with a specific initial key file:

runmqsfb -o <output file> -sf <initial key file>

Or to use a specific initial key file during runtime:

runmqsfb -f <config file> -sf <initial key file>

Before IBM MQ 9.2, a different credential protection system was used to protect credentials in the Bridge to Salesforce configuration files.

By default, runmqfsb protects credentials by using the new system, this means configuration files are not compatible with older versions of the Bridge to Salesforce.

To protect configuration files with the old credentials protection system, use the -sp 0 flag.

Important: The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22 2022 (see US Announcement letter 222-341).

IBM MQ clients that use cryptographic hardware

You can configure IBM MQ clients to use PKCS #11 cryptographic hardware to store private keys and certificates that are used in TLS communications. To access PKCS #11 devices, you must provide a password as part of the configuration string that is supplied to the IBM MQ client.

Important: Passwords supplied by using the CryptoHardware field in the MQCSO structure, or the queue manager SSLCRYP attribute cannot be protected by using this mechanism.

You can protect this password by using the runp11cred command, which can be found in the bin folder in the IBM MQ installation directory.

The runp11cred command prompts for the password to be encrypted to be entered, and returns the encrypted password. The encrypted password must be copied into the cryptographic hardware configuration string.

For example, if your cryptographic hardware configuration string is the following:

GSK_PKCS11=/usr/lib/pkcs11/PKCS11_API.so;tokenlabel;Passw0rd;SYMMETRIC_CIPHER_ON

When the runp11cred command prompts you to enter the password, enter Passw0rd. The command returns a string that is similar to the following:

<P11>!2!0TyDxrRaS6JUsjON9zfK6S4wEHmSNF0/ZsOdCaTD2dc=!MdpCoxGnFqPtZ1dTLQ58kg==

Replace the password in the cryptographic hardware configuration string with the string that is returned by the runp11cred command, to give the following string that contains the encrypted password:

GSK_PKCS11=/usr/lib/pkcs11/PKCS11_API.so;tokenlabel;<P11>!2!0TyDxrRaS6JUsjON9zfK6S4wEHm SNF0/ZsOdCaTD2dc=!MdpCoxGnFqPtZ1dTLQ58kg==;SYMMETRIC_CIPHER_ON

Store the cryptographic hardware configuration string that contains the encrypted password in ether the SSLCryptoHardware attribute in the SSL stanza of the client configuration file, or the MQSSLCRYP environment variable.

By default, the runp11cred command encrypts a password with a default initial key. To protect a password with your own initial key, specify the name of the file that contains the initial key by using one of the following mechanisms, in order of priority:

The -sf parameter to the runp11cred command.
The MQS_SSLCRYP_KEYFILE environment variable.

CAUTION:

Do not use the default initial key to encrypt passwords as it does not protect passwords securely.

If an initial key file is specified when the password is encrypted, you must also specify the name of the file that contains the initial key when the IBM MQ client runs. Specify the initial key file name by using one of the following mechanisms, in order of priority:

The MQS_SSLCRYP_KEYFILE environment variable.
The SSLCryptoHardwareKeyFile attribute in the SSL stanza of the client configuration file.

IBM MQ queue manager

The IBM MQ queue manager stores passwords internally in various attributes, for example, the queue manager KEYRPWD field. IBM MQ automatically encrypts the password before storing it in files on disk.

The keystore password can be protected by using either the IBM MQ password protection system, or a keystore stash file. For more information about these two methods, see Encrypting key repository passwords on AIX, Linux, and Windows.

When the queue manager encrypts a password, the default initial key is used unless an alternative key is specified by using the INITKEY attribute on the queue manager object. Set a unique, strong key before supplying any passwords that are to be encrypted.

Warning: Modifying the initial key after you supply the key repository passphrase does not cause the key repository passphrase to be encrypted with the new initial key. As such, changing the initial key without resupplying the key repository passphrase results in IBM MQ being unable to decrypt the key repository passphrase and therefore, unable to access the key repository.

For more information, see INITKEY.

IBM MQ C client applications

The IBM MQ C client libraries require passwords to access certain secured resources, for example a TLS keystore for applications that use TLS to connect to the queue manager.

To protect passwords with the IBM MQ password protection system, use the runmqicred command. The command is located in the MQ_INSTALLATION_PATH/bin directory.

The runmqicred command prompts for the password to be encrypted to be entered, and returns the encrypted password that can be used instead of a plain text password.

For example, if you choose to supply a TLS keystore password by using the MQKEYRPWD environment variable and your TLS keystore password is Passw0rd. When you run runmqicred, enter Passw0rd when prompted. The command returns a string that is similar to the following:

<MQI>!2!G4lRxBuiNfJ3uOeYTD3lG1hrL5NvVZLAlgZCX3Tn6d8=!pUDOErDfDi9+JFVa0usS7w==

Set this string as the value for the MQKEYRPWD environment variable:

export MQKEYRPWD="<MQI>!2!G4lRxBuiNfJ3uOeYTD3lG1hrL5NvVZLAlgZCX3Tn6d8=!pUDOErDfDi9+JFVa0usS7w=="
set MQKEYRPWD="<MQI>!2!G4lRxBuiNfJ3uOeYTD3lG1hrL5NvVZLAlgZCX3Tn6d8=!pUDOErDfDi9+JFVa0usS7w=="

By default, the runmqicred command encrypts a password with a default initial key. To protect a password with your own initial key, use one of the following mechanisms to specify the name of the file that contains the key, in order of priority:

The -sf parameter to the runmqicred command.
The MQS_MQI_KEYFILE environment variable.

CAUTION:

Do not use the default initial key to encrypt passwords as it does not protect passwords securely.

For more information, see Supplying the key repository password for an IBM MQ MQI client on AIX, Linux, and Windows.

Native HA configurations

Native HA log replication traffic between instances can be encrypted by using TLS. The certificates that are used to secure the log replication traffic are stored in a keystore that is specified in the NativeHALocalInstance stanza of the qm.ini file.

To protect the Native HA keystore password with the IBM MQ password protection system, use the runmqicred command.

The runmqicred command prompts for the password to be encrypted to be entered, and returns the encrypted password that should be used instead of a plain text password. Set the value of the KeyRepositoryPassword attribute in the NativeHALocalInstance stanza of the qm.ini file to the encrypted password that is returned by the command

The -sf parameter to the runmqicred command.
The MQS_MQI_KEYFILE environment variable.

CAUTION:

Do not use the default initial key to encrypt passwords as it does not protect passwords securely.

If you encrypt the keystore password with your own initial key, you must also specify the same initial key file by using the InitialKeyFile attribute in the NativeHALocalInstance stanza of the qm.ini file.

For more information, see NativeHALocalInstance stanza of the qm.ini file.

IBM MQ queue manager (AuthToken stanza in the qm.ini file)

From IBM MQ 9.3.4, IBM MQ MQI clients that connect to IBM MQ queue managers that run on AIX® or Linux® systems, can use authentication tokens to authenticate with the queue manager. The queue manager must be configured to accept authentication tokens and be able to access the token issuer's public key certificate or the secret key used to sign the token. The keystore that contains the trusted issuer's public key certificates or secret keys is secured with a password.

To protect the authentication token keystore password with the IBM MQ password protection system, use the runqmcred command to encrypt the password.

To encrypt the password with a specific initial key, use the -sf parameter to specify the path to the file that contains the initial key. If you do not provide the initial key, a default initial key is used.

CAUTION:

Do not use the default initial key to encrypt passwords as it does not protect passwords securely.

Important: If you supply an initial key file that contains the encryption key, the same initial key must be specified in the queue manager INITKEY attribute so that the queue manager can decrypt the password. If the queue manager INITKEY attribute is already set, use the same initial key when you run the runqmcred command. For more information about the queue manager INITKEY attribute, see INITKEY.

For example, to encrypt the authentication token keystore passwords using the initial key in the file /home/initial.key, issue the following command:

runqmcred -sf /home/initial.key

When prompted, enter the password that you want to encrypt.


5724-H72 (C) Copyright IBM Corp. 1994, 2024.
Enter password:
*************
<QM>!2!UnH/9hRXEGA0cenLVSGCW9a0s5A2vHDkTiA7vRv8ogc=!yhlsHFw7MIh48SvaYeTwRQ==

The encrypted password is output on the last line. Copy the encrypted password into a file and include the path to the file in the KeyStorePwdFile attribute of the AuthToken stanza in the qm.ini file.

For more information, see Configuring a queue manager to accept authentication tokens.