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.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.
[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
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.
- 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

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
andAES
.<?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>
- 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.
- 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.