Encrypting stored credentials in MFT

Managed File Transfer (MFT) requires several user IDs and credentials, which are stored in two XML files, and you can obfuscate these using the fteObfuscate command. From IBM® MQ 9.2.0, this command provides enhanced protection of the stored credentials.

Credential files

MQMFTCredentials.xml: This file contains the user Id and credentials for connecting to agents and coordination and command queue managers. The credentials to access key stores for secure connections to queue managers are also stored in the same file.; See MFT and IBM MQ connection authentication for details of the property values that define the location of the MQMFTCredentials.xml file.
ProtocolBridgeCredentials.xml: This file contains the user Id and credentials for connecting to protocol servers.

Encrypting credentials using the fteObfuscate command

From IBM MQ 9.2.0, the fteObfuscate command accepts the following parameters:

credentialsFileName, which is required
protection mode, credentialsKeyFile, and outputFileName, all of which are optional

See fteObfuscate for details of the parameters.

If you do not specify the protection mode, or a credentials key file, the command uses the default protection mode, and uses the latest algorithm, but with a fixed key to encrypt the credentials.

If you specify a protection mode of 0, and do not specify a credentials key file, the command works as in previous releases of the product. You receive a warning message on the console indicating usage of deprecated protection.

If you specify a protection mode of 0, and specify a credentials key file, you receive an error output on the console indicating that it is not valid to specify key file when using protection mode 0.

If you specify the protection mode of 1, and do not specify a credentials key file, the command uses the latest algorithm, but with a fixed key to encrypt the credentials.

If you specify the protection mode of 1, and specify a credentials key file, the command encrypts the credentials with the latest algorithm.

If you specify the protection mode of 1, or do not specify the protection mode, and specify a credentials key file that does not exist, an error is output on the console indicating that the file does not exist.

If you specify the protection mode of 1, or do not specify the protection mode, and specify a credentials key file that is not readable, an error is output on the console indicating that the file is not readable..

[MQ 9.2.4 Nov 2021] If you specify the protection mode of 2, and do not specify a credentials key file, the command uses protection mode 2 to encrypt credentials using the latest algorithm and a fixed key to encrypt.

[MQ 9.2.4 Nov 2021] If you specify the protection mode of 2, and specify a credentials key file, the command uses protection mode 2 to encrypt credentials using the latest algorithm and a user specified key to encrypt.

[MQ 9.2.4 Nov 2021] If you specify the protection mode of 2, or do not specify the protection mode, and specify a credentials key file that does not exist, an error is output on the console indicating that the file does not exist.

[MQ 9.2.4 Nov 2021] If you specify the protection mode of 2, or do not specify the protection mode, and specify a credentials key file that is not readable, an error is output on the console indicating that the file is not readable..

Decrypting credentials

You can specify the path to the initial key file in various places. In order to decrypt credentials that were encrypted using an initial key other than the default one, the name of the file containing the initial key needs to be provided to MFT in one of the following ways, in this order of precedence:

Using the Java Virtual Machine (JVM) property com.ibm.wqmfte.cred.keyfile, for example:
```
-Dcom.ibm.wmqfte.cred.keyfile=/usr/hime/credkeyfile.key
```

By setting a property in an agent, command, coordination, or logger properties file. The name of the properties file, and the property that needs to be set in it are shown in the following table:

Property file	Property name
agent.properties	agentCredentialsKeyFile
command.properties	commandCredentialsKeyFile
coordination.properties	coordinationCredentialsKeyFile
logger.properties	loggerCredentialsKeyFile

In the installation.properties file.
Instead of adding properties in individual properties files, you can add the commonCredentialsKeyFile property to the existing common installation.properties file, so that agent, logger and commands can use the same property.

You might have defined the various CredentialsKeyFile properties in multiple locations, so the path of the credentials key file being used for the:

Agent and logger, is logged to the output0.log file for that agent or logger.
Commands, is displayed on the console.

The Java system property com.ibm.wqmfte.cred.keyfile overrides all others. If the system property is not set, the agent looks into the agent.properties file, followed by the installation.properties file for the initial key file.

If the initial key file is still not found and you have set the protection mode on the fteObfuscate command to 1, the agent logs an error message in the output0.log file

If you have set the protection mode to 0 on the fteObfuscate command, a warning message is logged indicating the deprecation.

The logger and commands follow the same steps for locating the initial key file.

Protocol Bridge and Connect:Direct Bridge

Protocol Bridge uses a properties file, ProtocolBridgeProperties.xml, for connecting to FTP, SFTP, and FTPS servers. This properties file contains connection attributes required to connect to these servers.

A bridge agent restart is required if you modify the value of the credentialsFile or credentialsKeyFile attributes in the ProtocolBridgeProperties.xml file.

One of the attributes is credentialsFile, and the value contains the path to an XML file containing UID, or PWD, or Key required to connect to these servers. The default value for the attribute is ProtocolBridgeCredentials.xml and the file is in your home directory, just like the MQMFTCredentials.xml file.

<tns:credentialsFile path="$HOME/ProtocolBridgeCredentials.xml" />

Just like MQMFTCredentails.xml, you can encrypt ProtocolBridgeCredentials.xml with the fteObfuscate command. For decryption purpose, you can specify the required path to a credentials key file using the additional element credentialsKeyFile as shown in the following text. The path can contain environment variables.

<tns:credentialsKeyFile path="$HOME/CredKey.key"/>

Note: Specifying a value for the agentCredentialsKeyFile agent property, commonCredentialsKeyFile property in the installation.properties, or through the system property com.ibm.wqmfte.cred.keyfile does not have any impact on the value specified for the credentialsKeyFile attribute.

Similarly, Connect:Direct® Bridge uses ConnectDirectNodeProperties.xml to connect to the Connect:Direct server. The XML file contains required connection information, along with an attribute that defines path to the credentials XML file. This credentials XML file contains UID, or PWD, and additional information required to connect to the Connect:Direct server.

<tns:credentialsFile path="$HOME/ ConnectDirectCredentials.xml" />

Just like the ProtocolBridgeCredentials.xml file, you can encrypt ConnectDirectCredentials.xml with the fteObfuscate command. For decryption purpose, you can specify the required path to a credentials key file using the additional element credentialsKeyFile as shown in the following text. The path can contain environment variables.

<tns:credentialsKeyFile path="$HOME/CredKey.key”/>

You can specify the credentialsKeyFile element, without specifying the credentialsFile element in the ProtocolBridgeProperties.xml file.

If you do not specify the credentialsFile element, the default credential file ProtocolBridgeCredentials.xml is used by the protocol bridge agent, and the value of the key file specified in the credentialsKeyFile attribute is used to decrypt the credential file.

Similarly, you can specify the credentialsKeyFile element, without specifying the credentialsFile element in the ConnectDirectNodeProperties.xml file.

If you do not specify the credentialsFile element, the default credential file ConnectDirectCredentials.xml is used by the Connect:Direct bridge, and the value of the key file specified in the credentialsKeyFile attribute is used to decrypt the credential file.

Using the key from the data set on z/OS

On z/OS®, you can specify MQMFTCredentials and provide the credentials key file using a PDSE. See Configuring MQMFTCredentials.xml on z/OS.