MigrateEncryptedInfo utility

MigrateEncryptedInfo is a utility for changing the merchant key and re-encrypting all encrypted data in the database.

By default, it manages the following tables, as specified in DBUpdate.txt: USERREG, USERPWDHST, PATTRVALUE, ORDPAYINFO, ORDPAYMTHD, PPCEXTDATA, PPCPAYINST, MERCHCONFINFO, GRUSERAUTH, CSEDITATT, ISEDITATT. To run the MigrateEncryptedInfo utility more efficiently, first run the Database Cleanup utility on any of these tables that can have stale data that can be deleted, such as the PPCEXTDATA table. For information about optimizing MigrateEncryptedInfo, see: Optimizing the MigrateEncryptedInfo utility. There are two ways to specify the values of the merchant key to this tool. The first way is to provide the old and new merchant keys through command-line arguments. The second way is to retrieve the keys from calling out to the Key Locator Framework by using the "-k" parameter.

Important: You must specify your own merchant key and key encryption key values for the security of your HCL Commerce installation. Do not use the default values contained within the provided sample configuration files and documentation examples.

Managing custom tables using MigrateEncryptedInfo utility

Custom tables to be used for encryption should be encrypted using class DataReEncrypter. The Id ReEncryptUserPasswordHistory in the DBUpdate.txt file should be used to list the custom tables that will be encrypted. At least one table field should contain encrypted data and should be included in the DBUpdate.txt file.

Below is the example of how to add a custom table in DBUpdate.txt:

[DBTable]
TableName=<Custom_Table_Name>
TableColumns=<Encrypted_Values_Column_Names>
UniqueColumns=<Unique_Values_Column_Names>
[Parameter]
ID=OldEncryptionKey
DisplayID=OldEncryptionKey
Value=

TableName: Name of the Custom table to be use for encryption.
TableColumns: Contains column name of the table that stores encrypted values. Multiple columns may have encrypted data.
UniqueColumns: Contains the column name of the table that stores unique values. Multiple columns may have unique data. The UniqueColumns column should be of Numeric data type (for example, Integer), and it should be the custom table's primary key.

If any of the above details are missing in the DBUpdate.txt then the MigrateEncryptedInfo utility will not be able to decrypt or encrypt the data correctly.

Introduction

The MigrateEncryptedInfo utility is in the following directory:

utilities_root/bin/MigrateEncryptedInfo.sh
WCDE_installdir/bin/MigrateEncryptedInfo.bat

When the MigrateEncryptedInfo utility finishes, it generates the following log files.

CCInfoMigration.log
MKChangeUserAndCCInfoMigration.log
MigrateEncryptedInfoError.log
migrateFailedRecords_TABLENAME.log

in the following directory:

utilities_root/logs/
WCDE_installdir/logs/

Review the information in these log files and ensure that they do not contain any error messages.

If the error happened during the data decryption or encryption, the related failed data records are recorded in the log file utilities_root/logs/migrateFailedRecords_TABLENAME.log. The TABLENAME is the table name of failed data. It should be one of the USERREG, USERPWDHST, PATTRVALUE, ORDPAYINFO, ORDPAYMTHD, PPCEXTDATA, PPCPAYINST, MERCHCONFINFO, GRUSERAUTH, CSEDITATT, and ISEDITATT tables.

For example, if one record in ORDPAYINFO is decrypted with exception, it is recorded in the file utilities_root/logs/migrateFailedRecords_ORDPAYINFO.log. If the error occurred during the transaction, such as transaction commit, all of the data records in the batch are recorded, and one failed batch does not affect the others. The number of data records in one batch is configured by the parameter commit_count in the command line. The suggested value is 5000. After the error occurred, identify and resolve the root cause of the error according to the error messages and failed data records. Then:

Restore the database first and run the utility again.

Before you begin

Ensure that the HostName and HostJDBCPort parameters have been set in the utilities_root/schema/DBTYPE/migration/DBUpdate.txt configuration file.

Syntax

Diagram showing the MigrateEncryptedInfo utility. Parameters are described in the following list.

Parameter values

database_type: Your database type, DB2 or oracle.
instance_name: A mandatory parameter for the name of the instance that is updated. For example, demo.
num_of_threads: The number of threads that are created to re-encrypt the data. The recommendation is that this number should match the number of processors on the server that is running the utility.
commit_count: The number of records that are processed before the transaction is committed. The commit_count should be set to the maximum number of transactions that your database transaction log allows. A suggested value for this parameter is 5000.

If the merchant keys are not retrieved from the Key Locator Framework, these are the accepted parameters:

current_merchant_key

An optional parameter for the current merchant key, in clear text (ASCII) form. You should specify this parameter only if you are currently using a non-default merchant key, and you are now changing it to a new merchant key. In this case, you should also specify the new_merchant_key parameter. The utility detects that you are using the default key.

new_merchant_key

A required parameter in clear text (ASCII) form. If you are using a non-default merchant key, then this parameter is optional. It must conform to the following rules:

A 32 hexadecimal character must be used. Characters can be one of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, a, b, c, d, e, or f.
Must contain a minimum of one alphabetic character.
Must contain a minimum of one numeric character.
Must be in lowercase.
Cannot contain more than 4 identical consecutive characters.
For example, 1a1a1a1a1a1a1a1a2b2b2b2b2b2b2b2b.

If the merchant keys are retrieved from the Key Locator Framework, here is the accepted parameter:

-k keys_config_file_location: The current and new merchant keys are to be retrieved from the Key Locator Framework using the specified key configuration file. The absolute path of the file must be specified.
-interactive: Optional: The administrator is prompted for the new merchant key when this flag is specified. This flag can be used in offline mode only.
If you want to run the MigrateEncryptedInfo utility without stopping the server, then the -interactive parameter cannot be used.

Example 1

If your merchant key is stored in an external file and you want to change the value, complete these steps:

Stop the HCL Commerce instance.

If you are running the MigrateEncryptedInfo command to change keys while the Transaction server is offline, then define a new custom keys configuration file, CustomKeys.xml, similar to the following. Place it in a directory relative to an entry on the class path of the HCL Commerce application, such as, application_dir/WC/xml/config.

<?xml version="1.0" encoding="UTF-8"?>

<keys xmlns="http://www.ibm.com/xmlns/prod/WebSphereCommerce"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/WebSphereCommerce
xsd/WCKeys.xsd">

<key 
	name="MerchantKey"
	providerName="WC"
	status="current"
	className="com.ibm.commerce.security.keys.WCMerchantKeyImpl">

	<config
	name="instanceName" 
	value="demo"
	/>
</key>

<key 
	name="MerchantKey" 
	providerName="WC" 
	status="new"
	className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
	
	<config 
	name="keyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/merchantKey.xml"
	/>
	
	<config 
	name="keyEncryptionKeyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/KeyEncryptionKey.xml"
	/>
	
	<config 
	name="newKeyFile1"
	value="c:/temp/newMerchantKey1.xml"
	/>
	
	<config 
	name="newKeyFile2" 
	value="c:/temp/newMerchantKey2.xml"
	/>

</key>
</keys>

See Key Provider Implementations for merchant key for detail descriptions of each parameter and the format of the key files.

If you are running the MigrateEncryptedInfo command to migrate encryption from 3DES to AES, and the Transaction server is online, then HCL Commerce must have a way to differentiate data encrypted with the original key from data encrypted with the new key. For this reason, you must specify a unique version number to each key by using the version parameter.

In this circumstance, the MigrateEncryptedInfo utility decrypts data that is encrypted with the existing ("current") key and re-encrypts it with the new ("new") key.

Valid values for algorithm are 3DES and AES.

<?xml version="1.0" encoding="UTF-8"?>

<keys xmlns="http://www.ibm.com/xmlns/prod/WebSphereCommerce"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/WebSphereCommerce
xsd/WCKeys.xsd">

<key 
	name="MerchantKey"
	providerName="WC"
	status="current"
	className="com.ibm.commerce.security.keys.WCMerchantKeyImpl"
	version="2"
	algorithm="AES">
	
	<config
	name="instanceName" 
	value="demo"
	/>
</key>

<key 
	name="MerchantKey"
	providerName="WC"
	status="new"
	className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
	version="3"
	algorithm="AES"

	<config name="keyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/merchantKey.xml"
	/>

	<config name="keyEncryptionKeyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/KeyEncryptionKey.xml"
	/>

	<config name="newKeyFile1" 
	value="c:/temp/newMerchantKey1.xml"
	/>

	<config name="newKeyFile2" 
	value="c:/temp/newMerchantKey2.xml"
	/>
</key>
</keys>

Open a command prompt and navigate to the utilities_root/bin directory
Run the utility, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name:
- ```
MigrateEncryptedInfo db2 demo 4 5000 -k workspace_dir/WC/xml/config/CustomKeys.xml
```
Now that all the encrypted data is encrypted with the value retrieved from the "new" key provider, WCExternalFileMerchantKeyImpl, edit the keys configuration file as follow:
- Remove the "current" key provider
- Change the status of the "new" key provider to "current".
Start the HCL Commerce instance.
Deploy the changes in the custom XML files to the Transaction server Docker container. For example, merchantKey.xml, CustomKeys.xml, and KeyEncryptionKey.xml.

Example 2

If your merchant key is stored in an external file and you want to change the value by -interactive parameter and store it to a different file, complete these steps:

Stop the HCL Commerce instance.

Modify your existing custom keys configuration file (For example, application_dir/WC/xml/config/CustomKeys.xml) to resemble something similar to the following XML:

<?xml version="1.0" encoding="UTF-8"?>
<keys xmlns="http://www.ibm.com/xmlns/prod/WebSphereCommerce"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.ibm.com/xmlns/prod/WebSphereCommerce xsd/WCKeys.xsd">
	<key name="MerchantKey" providerName="WC" status="current"
		className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
		<config name="keyFile"
			value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/merchantKey.xml" />
		<config name="keyEncryptionKeyFile"
			value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/KeyEncryptionKey.xml" />
	</key>

	<key name="MerchantKey" providerName="WC" status="new"
		className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
		<config name="keyFile"
			value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/merchantKey1.xml" />
		<config name="keyEncryptionKeyFile"
			value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/KeyEncryptionKey1.xml" />
		<config name="newKeyFile1" value="c:/temp/newMerchantKey1.xml">
		<config name="newKeyFile2" value="c:/temp/newMerchantKey2.xml">	
	</key>
</keys>

See Key Provider Implementations for merchant key for detailed descriptions of each parameter and the format of the key files.

Open a command prompt and navigate to the utilities_root/bin directory
Run the utility, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name. Then, you are prompted to input the new merchant key.
- ```
MigrateEncryptedInfo db2 demo 4 5000 -k workspace_dir/WC/xml/config/CustomKeys.xml
```
Now that all the encrypted data is encrypted with the value retrieved from the "new" key provider, WCExternalFileMerchantKeyImpl, edit the keys configuration file as follow:
- Remove the "current" key provider
- Change the status of the "new" key provider to "current".
Use a secure removal tool (SDelete or SRM) to remove the old key files (for example, merchantKey.xml and KeyEncryptionKey.xml).
Deploy the changes in the custom XML files to the Transaction server Docker container. For example, merchantKey.xml, CustomKeys.xml, and KeyEncryptionKey.xml.