Encrypting configuration files in Payment Feature Services

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

Overview
Installing and configuring the utility to use with Red Hat OpenShift
Running the utility
Update the Red Hat OpenShift application secret with the encryption parameters
Example of encrypting properties for Red Hat OpenShift containers

Overview

Most of the Payment Feature Services components support DES, triple DES, and newer encryption algorithms. 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 shown in the following list:

.ena: The file is encoded with AES.
.enp: The file is encoded with PBEWithMD5AndDES.
.enc: The file is encoded with DES.
.en3: The file is encoded with triple DES (DES3).

Note: DES encryption is supported only to maintain compatibility for existing encrypted configuration files. For the Payment Feature Services components that support the newer encryption algorithms, you need to evaluate what encoding to use for your environment.

In addition, almost all of the components support partial encoding of their configuration properties. For partial encoding, use the newConfigurationFile property of a plain text configuration file to specify the name of an encrypted properties file. The configuration values from the encrypted file are added to, or override, the values from the plain text properties file. Users can use this property 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.

The Business Rules, Gateway Server, and Transaction Server configuration files have placeholders that are replaced with real values when the associated container is started. These placeholders cannot be replaced when the configuration file is encrypted. If you need to encrypt your configuration file, replace the placeholders with the actual values for the properties before you encrypt the file. For example, replace the placeholder for the database password with the actual password in the dbConnectPwd = %DBPASS% line of the configuration file. If the database password is mydbpass, the database password line in the configuration file needs to be dbConnectPwd = mydbpass.

The following table 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
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
Business Rules 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
Transaction Server	Full or partial encoding of its configuration properties file Scheduler, extraction, and listener profile XML files	DES Triple DES (DES3) AES PBEWithMD5AndDES

Installing and configuring the utility to use with Red Hat OpenShift

The encryption utility is in the data setup utility compressed file that is in the artifacts container for FTM offerings that use Payment Feature Services components. You also need to get the compressed file that has the templates for the configuration files for the Payment Feature Services components. These compressed files are shown in the following list.

dsu.zip
j2se-config.zip

You can also use the /home/ftmuser/ftm/artifacts/listing.txt file in the artifacts container to help you find the location of the encryption utility and of the configuration files that you want to use.

The encryption utility also needs library files from the Payment Feature Services component to run. These library files are in compressed files that are in the artifacts container.

For the Business Rules Server, get the j2se-brs-jars.zip compressed file.
For the Business Rules Manager, get the j2se-brm-jars.zip compressed file.
For the Gateway Server, get the j2se-gateway-jars.zip compressed file.
For the Transaction Server, get the j2se-its-jars.zip compressed file.

Connect to the Red Hat® OpenShift® environment and get the compressed files that you need from the artifacts container. Use a user ID with the permissions that are needed for the project where your FTM offering is deployed. For more information about getting the compressed files, see Getting the files from the artifacts container for your FTM offering.

Extract the files from the data setup utility compressed file and the other compressed files. The encryption utility is at the following location.

The path for Linux® is extract_directory/dsu/Base/utilities/Encryption/unix/encode.sh.

The utility is run from the directory where you extracted it to. The following environment variables must be set before you can run the utility.

Set FTM_JRE_HOME to extract_directory/dsu/_jvm64/jre.
Set FTM_LIB_DIR to the path to the library files that you extracted for the Payment Feature Services component. For example, if you extracted the compressed file for Gateway Server, set FTM_LIB_DIR to extract_directory/j2se-gateway-jars/shared/v405/pfs/Gateway/lib.

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 shown in the following example.

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

The parameters for the encryption utility are described in the following table.

Table 2. Encryption utility parameters
Parameter	Values	Description
?		Displays the help text for the utility.
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. Notes: The file extension of the encrypted file must be one of the recognized file extensions or the components in Table 1 can't use the file. When the name of the encrypted file is changed, 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 values that are shown in the following list: 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. Notes: To keep your configuration files more secure, use one of the newer encryption algorithms instead of DES. DES encryption is supported only to maintain compatibility for existing encrypted configuration files. 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 the properties or configuration file is encrypted. If this parameter is specified without its passphrase, the user is prompted for a passphrase.
-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.

Update the Red Hat OpenShift application secret with the encryption parameters

If you use the passphrase, mode, or padding parameters to encrypt your configuration file, you also need to update the application secret for your FTM installation. Set the value of the J2SE_PROPERTIES_ENCR_PARAMS key to the encryption utility parameter string that you used to encrypt the Business Rules, Gateway Server, and Transaction Server properties files. For example, if you used all of these parameters when the file was encrypted, the parameter string has the following format:
-pass=passphrase -mode=mode -pad=padding

For more information about the application secret that has the J2SE_PROPERTIES_ENCR_PARAMS key, see Create an application secret for your FTM installation on Red Hat OpenShift.

Example of encrypting properties for Red Hat OpenShift containers

The following example shows how to partially encrypt a Gateway Server properties file. The procedure is similar for the Business Rules Server, Business Rules Manager, and Transaction Server components.

Ensure that the encryption utility is installed and configured. For more information, see Installing and configuring the utility to use with Red Hat OpenShift. For this example, /tmp/artifacts is used as the directory where you extracted the compressed files to.
In this example, some sensitive values in the Gateway Server properties file are being encrypted, so extract the j2se-gateway-jars.zip file to the /tmp/artifacts directory.
Go to j2se-config/gw directory, which is where the Gateway Server configuration file template is located.
```
cd /tmp/artifacts/j2se-config/gw
```

Create a file for the properties that are to be encrypted. The following table shows the default names that are used for the encrypted properties files for each Payment Feature Services component.

Table 3. Default source file names for the encrypted properties
Payment Feature Services component	Encrypted properties source file name
Business Rules Server	configBR_secret.properties
Business Rules Manager	pdmconfig_secret.properties
Gateway Server	izxconfig_secret.properties
Transaction Server	configITS_secret.properties

Identify which properties that you want to encrypt and add the name and value pairs for those properties to the new izxconfig_secret.properties file that you created. In this example, only the dbConnectPwd database password property is to be encrypted, so add the following line with your database password to the file.
```
dbConnectPwd = yourdb2pass
```

Encrypt the file by running the utility. The encrypted file for Gateway Server is created in the /tmp/artifacts/j2se-config/gw/ directory.

/tmp/artifacts/dsu/Base/utilities/Encryption/unix/encode.sh /tmp/artifacts/j2se-config/gw/izxconfig_secret.properties

The following table shows the default DES encrypted properties file names for the Payment Feature Services components.

Table 4. Default DES-encrypted properties file names
Payment Feature Services component	Encrypted properties file name
Business Rules Server	configBR_secret.properties.enc
Business Rules Manager	pdmconfig_secret.properties.enc
Gateway Server	izxconfig_secret.properties.enc
Transaction Server	configITS_secret.properties.enc

In the /tmp/artifacts/j2se-config/gw directory, update the Gateway Server sample configuration property file that you want to use.
1. Remove the properties that you moved to the encrypted properties file. In this example, you can remove the database password property, dbConnectPwd.
2. Remove the comment from the following line with the newConfigurationFile property.
```
# newConfigurationFile = /opt/ibm/ftm/j2se-gw-config/izxconfig_secret.properties.enc
```
  Verify that the path to the encrypted file is correct by checking where the file is on the pv-ftm-application persistent volume.
Copy your updated sample configuration file from the /tmp/artifacts/j2se-config/gw directory to the configmap for the Gateway Server. The Gateway Server uses this configuration file, which has no database password property, and uses the encrypted properties file that was specified in the newConfigurationFile property. For more information about providing configuration files in a configmap, see Customizing the configuration files in a ConfigMap.
Copy the /tmp/artifacts/j2se-config/gw/izxconfig_secret.properties.enc encrypted configuration file to the same configmap that you copied your updated sample configuration file to.
Use the Red Hat OpenShift Container Platform to restart the Gateway Server pods so that they all use the updated configuration file.
Verify that the configuration file was updated correctly. In the Gateway Server pods, display the Gateway Server configuration file to make sure that it does not contain the dbConnectPwd property. The properties files are located in the /opt/ibm/ftm/shared/v405/pfs/Gateway/properties directory.