Protecting passwords in IBM MQ component configuration files

In order to use certain features of IBM® MQ, passwords might have to be supplied either directly into IBM MQ or inside configuration files read by that feature. From IBM MQ 9.2.0, a new password protection system is implemented that allows the protection of passwords within these configuration files.

You should protect passwords in configuration files. The following list explains the common terminology used for each component:

Initial key

The encryption key you provide for use in the encryption process.

For each of the components listed, you can supply an initial key file that contains an encryption key to use, when protecting or reading passwords stored in the configuration file of that component.

The file must contain a single line of at least one character.

There is no limit or requirement on the length of the encryption key, however, your key file should contain at least 16 characters. For example, your file could contain the following:

Th1sIs@n3Ncypt|onK$y

In addition, the initial key file you provide should:

Contain a unique encryption key
Be adequately protected using the operating system permissions.

Default initial key

The default encryption key used, if you do not supply an initial key when encrypting data. However, you should not use the default initial key.

Plain text string

The string that is encrypted, commonly a password

Encoded password

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

Important: Encoded password strings that you have 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 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 using cryptographic hardware

Advanced Message Security

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

[MQ 9.2.2 Mar 2021] Advanced Message Security (AMS) MQI clients or queue managers configured to perform MCA Interception might require access to PKCS#11 cryptographic hardware, or PEM files which contain private keys to protect messages.

In order to access these, a password must be provided in the AMS configuration file 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 specified, using the -f flag.

Two runamscred programs have been 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.
You should verify that all the necessary sensitive information has been protected after running runamscred.
You can supply the protected file as normal to AMS enabled applications.

To override or provide the initial key file to use during runtime of AMS applications, or when protecting a keystore configuration file using runamscred, use one of the following four mechanisms. In order of priority, these are the:

-sf parameter (runamscred only)
MQS_AMSCRED_KEYFILE environment variable
amscred.keyfile parameter in the configuration file
Default initial key file if none of the above options is specified.

Attention: You should not use the default initial key.

Prior to 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 using the new system. This means 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 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.

See Encrypting stored credentials in MFT for more information.

To protect sensitive information stored in these files, use the fteObfuscate command within the file specified, 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:

You should verify that all the necessary sensitive information has been protected after running fteObfuscate.
You can supply the protected file as normal to MFT.

At runtime, 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.2.0 Fix Pack 15, the name of this Java system property was misspelled in the product code as com.ibm.wqmfte.cred.keyfile. From IBM MQ 9.2.0 Fix Pack 15, 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.2.0 Fix Pack 15, use the property com.ibm.wqmfte.cred.keyfile.
In the agent, logger, command,s and coordination property files.
In the installation.properties file.

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

By default, fteObfuscate protects credentials 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 flag.

IBM MQ Internet Pass-Thru

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

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

mqiptPW

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

mqiptPW -sf <intial key file>

See Specifying the password encryption key for more information.

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 runtime, provide the initial key file to use through the following four mechanisms. In order of priority, these are:

Through the -sf parameter when starting MQIPT.
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.

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

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

To protect keystore passwords using 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. 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:

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>

Prior to 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 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).
For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.2.0 CSU 21.

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>

Prior to 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 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 using cryptographic hardware

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

Important: Passwords supplied through the MQSCO.SSLCryptoHardware structure string, or the queue manager SSLCRYP attribute cannot be protected using this mechanism.

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

The runp11cred command prompts you to securely enter a password to protect, and returns a string that needs to be copied into the cryptographic hardware configuration string.

For example, if your GSK_PKCS11 is:

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

then, when prompted, enter Passw0rd. runp11cred returns a string that looks similar to the following:

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

Copy the string in bold in place of the Passw0rd in the GSK_PKCS11 string:

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

To protect a password with a specific initial key, use one of the following mechanisms. In order of priority, these are the:

-sf parameter (runp11cred command only)
MQS_SSLCRYP_KEYFILE environment variable
SSLCryptoHardwareKeyFile SSL Stanza attribute (IBM MQ client only)
Default initial key file if none of the above options is specified.

Attention: You should not use the default initial key.