fteObfuscate (encrypt sensitive data)

The fteObfuscate command encrypts sensitive data in credentials files. This prevents anyone who gains access to the file from being able to read the sensitive data.

Purpose

User name and password properties in credentials files can be encrypted. These properties are transformed to a new related property, with a Cipher suffix. For example:

<!--
  MQMFTCredentials properties before
-->
<tns:logger name="logger1" user="user1" password="passw0rd" />
<tns:file path="$HOME/trust.jks" password="passw0rd" />

<!--
  MQMFTCredentials properties after
-->
<tns:logger name="logger1" userCipher="e71vKCg2pf" passwordCipher="se71vKCg" />
<tns:file path="$HOME/trust.jks" passwordCipher="e71vKCg2pf" />

<!--
  ProtocolBridgeCredentials Properties before
-->
<tns:user name="Fred" serverUserId="fred" serverPassword="passw0rd" />

<!--
  ProtocolBridgeCredentials properties after
-->
<tns:user name="Fred" serverUserIdCipher="e51vVCg2pf" serverPasswordCipher="se51vBCg" />

<!--
  ConnectDirectCredentials properties before
-->
<tns:user name="fteuser" ignorecase="true" pattern="wildcard"
          cdUserId="cdUser" cdPassword="cdPassword" pnodeUserId="pnodeUser"
          pnodePassword="pnodePassword">
  <tns:snode name="snode1" pattern="wildcard" userId="snodeUser" password="snodePassword"/>
</tns:user>

<!--
  ConnectDirectCredentials properties after
-->
<tns:user name="fteuser" ignorecase="true" pattern="wildcard"
          cdUserIdCipher="e71vKCg2pf" cdPasswordCipher="se71vKCg"
          pnodeUserIdCipher="2f1vgCg6df" pnodePasswordCipher="e71vKCg2pf">
  <tns:snode name="snode1" pattern="wildcard" userIdCipher="e51vVCg2pf" passwordCipher="se51vBCg"/>
</tns:user>

The preferred formats are:

Managed File Transfer (MFT)


<tns:qmgr mqPasswordCipher="mqmftcred!1!kvAzYv/1aCMfSQ5igkFVmQ==!f4rX5KL7aFKHJl7Ln0X+OQ==" 
mqUserIdCipher="mqmftcred!1!w2PQGhQcyq1NwYzGItz0VA==!Q40i2rRSEMGwrx6gnRFe8g==" 
name="MFTQM" user="JOHNDOE"/>

ProtocolBridgeCredentials


<tns:agent name="agent3">                                        
  <tns:serverHost name="ftpsServer" 
                            keyStorePasswordCipher="mqmftcred!1!w2PQGhQcyq1NwYzGItz3VA==!Q40i2rRSEMGwrx6gnRFe8g==" 
trustStorePasswordCipher="mqmftcred!1!w2PQGhQcyq1NwYzGKtz0VA==!Q40i2rRSEMGwrx6gnRFe8g==">
   </tns:serverHost>
 </tns:agent>

ConnectDirectCredentials


<tns:agent name="CDAGENT01">
        <tns:pnode name="cdnode*" pattern="wildcard">
          <tns:user name="MUSR_.*"
            ignorecase="true"
            pattern="regex"
            cdUserIdCipher="mqmftcred!1!w2PQGhQcyq1NwYzGItz0VA==!Q40i2rRSEMGwrx6gnRFe8g=="/>            cdPasswordCipher=="!mqmftcred!1!w2PQGhQcyq1NwYzGItz0VA==!Q40i2rRSEMGwrx6gnRFe8g=="/>            pnodeUserIdipher="mqmftcred!1!w2PQGhQcyq1NwYzGItz0VA==!Q40i2rRSEMGwrx6gnRFe8g=="/>            pnodePasswordCipher="mqmftcred!1!w2PQGhQcyq1NwYzGItz0VA==!Q40i2rRSEMGwrx6gnRFe8g=="/>          <tns:snode name="cdnode2" pattern="wildcard" userId="sue" passwordCipher="!mqmftcred!1!w2PQGhQcyq1NwYzGItz0VA==!Q40i2rRSEMGwrx6gnRFe8g=="/>
          </tns:user>
        </tns:pnode>
      </tns:agent>

Usage notes

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.

To encrypt credentials with a specific initial key, specify the name of the file that contains the initial key by using the -sf parameter to the fteObfuscate command.

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, see Encrypting stored credentials in MFT.

Note: When a file, for example, the MQMFTCredentials.xml file, has been encrypted using an initial key file, MFT commands that need to use information from the encrypted credentials files will need to identify the location of the initial key file via a JVM property, like this:

On Linux®:

export BFG_JVM_PROPERTIES="-Dcom.ibm.wmqfte.cred.keyfile=..."

On Windows:

set BFG_JVM_PROPERTIES=-Dcom.ibm.wmqfte.cred.keyfile=...

Syntax

The syntax is as follows:

fteObfuscate

Required parameters

-f credentials_file_name: Required. The name of the file that contains the credentials to encrypt.; Note: This parameter replaces the -credentialsFile parameter that is deprecated from IBM MQ 9.2.0.

Optional parameters

-sp protection_mode

Optional. The protection mode that is used for encrypting credentials. One of the following values can be specified:

0: Use the deprecated credentials protection mode.
1: Use the more secure credentials protection method that is compatible with IBM MQ 9.2.0.; Consider migrating any stored credentials to the enhanced protection that is provided by protection mode 2.
2: Use the latest credentials protection mode. This mode is the most secure credentials protection mode.; This is the default value.

-sf credentials_key_file

Optional. The name of the file containing the credentials key. If this parameter is omitted, the command uses the default credentials key. For more information, see Protecting passwords in IBM MQ component configuration files.

-o output_file_name

Optional. Name of the file to output the protected credentials.

-sm

Encrypts passwords using a FIPS compliant cryptographic library.

You cannot use this parameter with the -sp parameter set to 0.

This parameter is not available on IBM i or z/OS®.

-? or -h

Optional. Displays command syntax.

Examples: protection mode 2 (default protection mode)

To encrypt credentials in the MQMFTCredentials.xml file, with the default initial key and the latest protection mode, issue the following command:

fteObfuscate -f /usr/home/MQMFTCredentials.xml

To encrypt credentials in the MQMFTCredentials.xml file, with the initial key in the /var/mqmft/credKeyfile.key file and the latest protection mode, issue the following command:

fteObfuscate -sf /var/mqmft/credKeyfile.key -f /usr/home/MQMFTCredentials.xml

To encrypt credentials in the MQMFTCredentials.xml file, with the initial key in the /var/mqmft/credKeyfile.key file and the latest protection mode, and output the encrypted credentials to another file, issue the following command:

fteObfuscate -sf /var/mqmft/credKeyfile.key -sp 2 
             -f /usr/home/MQMFTCredentials.xml -o /usr/home/enccred.xml

To encrypt credentials in the ProtocolBridgeCredentials.xml file, with the initial key in the /var/mqmft/credKeyfile.key file and the latest protection mode, issue the following command:

fteObfuscate -sf /var/mqmft/credKeyfile.key 
             -f /usr/home/ProtocolBridgeCredentials.xml

Examples: protection mode 1

To encrypt credentials in the MQMFTCredentials.xml file, with the initial key in the /var/mqmft/credKeyfile.key file and protection mode 1, issue the following command:

fteObfuscate -sf /var/mqmft/credKeyfile.key -sp 1 -f /usr/home/MQMFTCredentials.xml

To encrypt credentials in the MQMFTCredentials.xml file, with the initial key in the /var/mqmft/credKeyfile.key file and protection mode 1, and output the encrypted credentials to another file, issue the following command:

fteObfuscate -sf /var/mqmft/credKeyfile.key -sp 1 
             -f /usr/home/MQMFTCredentials.xml -o /usr/home/enccred.xml

Examples: protection mode 0

To encrypt credentials in the MQMFTCredentials.xml file, with the deprecated protection mode, issue the following command:

fteObfuscate -f /usr/home/MQMFTCredentials.xml -sp 0

Using data sets on z/OS

To encrypt the credentials in the data set TEST.CREDS(CREDS) and output the encrypted credentials to an XML file, issue the following command:

fteObfuscate  -f "//test.creds(creds)" -o enc.xml

Encrypt the credentials in the data set TEST.CREDS(CREDS) with the initial key in the data set TEST.CREDS(KEY), issue the following command:

/fteObfuscate -f "//test.creds(creds)" -sf "//test.creds(key)"

Return codes

Table 1. Return code names and descriptions
Return code	Description
0	Command completed successfully
1	Command ended unsuccessfully