Improvements to Managed File Transfer security from IBM MQ Version 9.2

Managed File Transfer ( MFT) requires several user IDs and credentials, which are stored in two XML files, and we can obfuscate these using the fteObfuscate command. This command has been enhanced to improve the 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 Version 9.2, the revised version of this 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 we 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..


Decrypting credentials

We 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:
  1. Use the Java Virtual Machine (JVM) property com.ibm.wqmfte.cred.keyfile, for example:
    -Dcom.ibm.wmqfte.cred.keyfile=/usr/hime/credkeyfile.key
  2. In agent, logger, commands, and coordination property files.Each of these property files contains and additional specific CredentialKeyFile property. See:

    for details of these properties.

  3. In the installation.properties file.

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

We 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 system property 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 we 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, we can encrypt ProtocolBridgeCredentials.xml with the fteObfuscate command. For decryption purpose, we 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, we can encrypt ConnectDirectCredentials.xml with the fteObfuscate command. For decryption purpose, we 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.

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

If we 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, we can specify the credentialsKeyFile element, without specifying the credentialsFile element in the ConnectDirectNodeProperties.xml file.

If we 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.


Use the key from the data set on z/OS

On z/OS, we can specify MQMFTCredentials and provide the credentials key file using a PDSE. See The MFT credentials file for more information.

Parent topic: Securing Managed File Transfer


Related information