Encrypting configuration files in Payment Feature Services

To help protect sensitive configuration information, several Payment Feature Services components support using properties and configuration files that are encrypted. Payment Feature Services provides an encryption utility to help the user create these encrypted files.

Overview

Most of the Payment Feature Services components support both DES and triple DES encryption. The same encryption algorithm does not need to be used for all of the properties and configuration files for a single component. The components use the file extension of the properties file to determine which encryption algorithm was used to encode the file. The recognized file extensions are:

.enc: The file is encoded using DES
.en3: The file is encoded using triple DES (DES3)

For example, the XML files that are used internally by Transaction Server can be encrypted. Transaction Server uses the file extension of the XML files that are specified in its configuration properties to determine whether any of the files are encrypted. In the following example properties, two of the XML files are encrypted using DES and one is encrypted using triple DES:

extractionConfigXml = ..\\xml\\MyExtractionProfile.xml.enc
listenerConfigXml = ..\\xml\\MyListenerProfile.xml.enc
schedulerConfigXml = ..\\xml\\MyScheduler.xml.en3

Note: Ensure that the extension matches the encoding algorithm that is used or the file becomes unreadable.

In addition, almost all of the components support partial encoding of their configuration properties. If the name of an encrypted properties file is specified in the newConfigurationFile property of a plain text configuration file, the configuration values from the encrypted file are added to or override the values from the plain text properties file. This allows users to keep their secure information, such as user IDs and passwords, separate from the rest of their basic configuration properties. For example, the user can use the encryption utility to create a file that is called mysecure.properties.en3 that contains only the user ID and password properties that are needed to access the database. To use this secure properties file for a component that supports partial encoding, update the plain text properties file for that component to set the value of newConfigurationFile to mysecure.properties.en3.

Table 1 shows the components that support encrypted files and which files can be encrypted.

Table 1. Components and files supported by the encryption utility
Component name	Files supported	Algorithms supported
Archive Server	Full encoding of the XltSrvr.ini configuration file	DES
Business Rules Server	Full or partial encoding of its configuration properties file	DES Triple DES (DES3) AES PBEWithMD5AndDES
Data Setup Utility	Full or partial encoding of its import and export properties files	DES Triple DES (DES3) AES PBEWithMD5AndDES
Distribution Manager	Full or partial encoding of its configuration properties file	DES Triple DES (DES3) AES PBEWithMD5AndDES
Gateway Server	Full or partial encoding of its configuration properties file	DES Triple DES (DES3) AES PBEWithMD5AndDES
Application Shutdown Utility	Full or partial encoding of its configuration properties file	DES Triple DES (DES3) AES PBEWithMD5AndDES
Transaction Server	Full or partial encoding of its configuration properties file Scheduler, extraction, and listener profile XML files	DES Triple DES (DES3) AES PBEWithMD5AndDES

Locating and configuring the utility

The encryption utility is installed as follows:

For the Windows operating system: install_directory\shared\v306\pfs\utilities\Encryption\win\Encode.bat
For AIX® and Linux: install_directory/shared/v306/pfs/utilities/Encryption/unix/encode.sh

The utility is normally run from the cmd directory of the component with the configuration files that are being encrypted. However, not all of the Payment Feature Services components, such as the Archive Server and the data setup utility, have the proper directory structure to support running the utility. For those components, the utility must either be run from the directory structure of one of the components that supports it, or the following environment variables must be set for the utility to run in the alternative directory structure:

Set FTM_JAVA_HOME to install_directory\shared\v306\pfs\_jvm\jre
Set FTM_LIB_DIR to the lib directory of a component that can run the utility. For example, to use the Transaction Server component to run the utility, set this variable to install_directory\shared\v306\pfs\ITS\lib when Transaction Server is installed in its default directory.

Running the utility

The encryption utility can be used to encrypt certain properties and configuration files for the supported Payment Feature Services components. The syntax for running the encryption utility is:

Encode propertiesFile [-OUT=outputFilename -ALG=encryptionAlgorithm]

The parameters for the encryption utility are described in Table 2.

Table 2. Encryption utility parameters
Parameter	Values	Description
propertiesFile	A user-specified file name	The name of the properties or configuration file to be encrypted. The file name can be specified with a full or relative path.
-OUT=outputFilename	For this parameter, outputFilename is a user-specified file name	The name of the encrypted properties or configuration file that is created by the utility. By default, the utility appends the file extension for the encryption algorithm to the end of the file name that is provided in the propertiesFile parameter. Use this parameter to specify a different name for the encrypted file. This parameter is optional. Note: The file extension of the encrypted file must be one of the recognized file extensions or the components in Table 1 are not able to use the file When changing the name of the encrypted file, ensure that the extension matches the encoding algorithm that is used or the file becomes unreadable
-ALG=encryptionAlgorithm	For this parameter, encryptionAlgorithm is one of the following values: DES3 DESede AES PBE	By default, the utility uses the DES algorithm. To use triple DES instead, specify this parameter as either DES3 or DESede. Triple DES (DES3) encryption is considered more secure than the default single DES encryption. This parameter is optional. Note: Not all of the components support DES3. Table 1 shows the encryption algorithms that are supported by each of the components.
-klen=keylength	For this parameter, keylength is a user-specified length	The length of the key to use for the encryption. This parameter is required only when the encryption algorithm is AES or PBE (PBEWithMD5AndDES).
-pass=passphrase	For this parameter, passphrase is a user-specified password	The passphrase to use when encrypting the properties or configuration file. If this parameter is specified without its passphrase, the user is prompted for a passphrase. If this parameter is not specified at all, the file is encrypted without using a passphrase. This parameter is optional.
-MODE=mode	Any mode that is supported by the algorithms that are listed in Table 1 are valid.	The mode that is used by the algorithm during encryption and decryption. The mode is usually the value in the middle of the transformation string for the cipher: `DES/ECB/PKCS5Padding`. This parameter is optional, but it is required when the padding type is specified. ECB is the default mode for DES, DES3, and AES. CBC is the default mode for PBE.
-PAD=padding	Any padding type that is supported by the algorithms that are listed in Table 1 are valid.	The padding type that is used by the algorithm during encryption and decryption. The padding type is usually the value at the end of the transformation string for the cipher: `DES/ECB/PKCS5Padding`. This parameter is optional, but it is required when the mode is specified. PKCS5Padding is the default padding type.

The following example shows how to fully encrypt the Transaction Server properties file on the Windows operating system. The procedure is similar for the other Payment Feature Services components and supported operating systems.

Start a command prompt.
Change to the directory where Transaction Server is installed. By default, it is the install_directory\shared\v306\pfs\ITS\cmd directory.
Run the utility to encrypt the Transaction Server properties file:
```
Encode ..\profiles\config.properties
```
This example uses the DES algorithm and the default file name for the encrypted file.
Change to the ..\profiles directory. The newly encrypted file is called config.properties.enc. When a text editor is used to look at this file, none of the configuration values should appear as plain text.
Make sure that the original, plain text config.properties file is copied to a secure location as a backup. Then, remove it from this directory.
Modify the Transaction Server startup to use the config.properties.enc file instead of the config.properties file
After the Transaction Server starts, verify that its configuration properties are correct. For example, use the list cfg command to verify the properties for Transaction Server.