Encrypting stored credentials in MFT

The Managed File Transfer (MFT) configuration contains several user IDs and passwords. These credentials are stored in two XML files. You can obfuscate these credentials by using the fteObfuscate command.

Credential files

MQMFTCredentials.xml: This file contains user IDs and passwords that are used to connect to agent, coordination, and command queue managers. This file also contains passwords that are used to access keystores that are used to secure connections to queue managers.; 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 user IDs and passwords that are used to connect to protocol servers.

Encrypting credentials

To protect sensitive information that is stored in these files, use the fteObfuscate command.

An encryption key, which is known as the initial key, is used to encrypt sensitive data in credentials files. You can provide a file that contains the initial key when you run the fteObfuscate command. Create the initial key file before you run the command. If you do not provide the initial key, the default initial key is used.

CAUTION:

The default initial key is the same for all IBM® MQ installations. To protect passwords securely, supply an initial key that is unique to your installation when you encrypt passwords.

For more information about the fteObfuscate command, see fteObfuscate.

Decrypting credentials

If you specify an initial key file when credentials in the MFT configuration are protected, you must also specify the same initial key file when MFT starts. The following mechanisms can be used to specify the name of the initial key file, in order of priority:

By using a Java system property, for example:
```
-Dcom.ibm.wmqfte.cred.keyfile=/usr/hime/credkeyfile.key
```
Note:
- 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 checking if a user has specified a file containing the initial key that should be used for encrypting and decrypting credentials. This allows you to use the correct spelling of the property name, while maintaining backwards compatibility 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.
.

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.

If you have defined the various CredentialsKeyFile properties in multiple locations:

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.
The path of the credentials key file being used for the commands, is displayed on the console.

The Java system property com.ibm.wmqfte.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"/>

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.

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.