MigrateEncryptedInfo utility

MigrateEncryptedInfo utility
MigrateEncryptedInfo is a utility for changing the merchant key and re-encrypting all encrypted data in the database.
By default, it handles 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. 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.

Introduction
The MigrateEncryptedInfo utility is in the following directory:

(Linux) utilities_root/bin/MigrateEncryptedInfo.sh

(Developer) 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:

(Linux) utilities_root/logs

(Developer) 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 beginning

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 the 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. Specify if currently using a non-default merchant key, and we are now changing it to a new merchant key. In this case, specify the new_merchant_key parameter. The utility detects that we are using the default key.

new_merchant_key

A required parameter in clear text (ASCII) form. If we 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.
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 the instance.xml file and we want to change the value in that file, run the utility as follows, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name:
MigrateEncryptedInfo db2 demo 4 5000 1234567890abcdef1234567890abcdef abcdef1234567890abcdef1234567890
Note: This example is setting the num_of_threads value to 4 (for a 4-processor server) and the commit_count to 5000. Then complete the following steps:

Enter the Utility server Docker container.
Open the opt/WebSphere/CommerceServer90/instances/demo/xml/demo.xml file and find the new encrypted merchant key by searching for MerchantKey.
Customize the opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/wc-server.xml with the new encrypted merchant key.
Deploy wc-server.xml to the Transaction server Docker container.

Example 2

If your merchant key is stored in the Utility server Docker container instance.xml file and we want to change the value and store the value in an external file, complete these steps:
Define a new custom keys configuration file, CustomKeys.xml, similar to the following and place it in a directory relative to an entry on the class path of the WebSphere 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.
cd utilities_root/bin directory
Run the utility, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name:

(Linux)
MigrateEncryptedInfo db2 demo 4 5000 -k application_dir/WC/xml/config/CustomKeys.xml

Add a KeysConfigFile attribute in the <Instance> section of the wc-server.xml file in the Transaction server Docker container. This attribute points to an entry on the classpath of the WebSphere Commerce application. For example,
KeysConfigFile = "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".

Deploy the changes in the custom XML files to the Transaction server Docker container. For example, merchantKey.xml, CustomKeys.xml, and KeyEncryptionKey.xml.
Note: In clustered environments, if any of your changed custom XML files are outside the EAR, for example merchantKey.xml and KeyEncryptionKey.xml, we must manually copy these files to the other servers.
Example 3

If your merchant key is stored in an external file and we want to change the value, complete these steps:
Stop the WebSphere 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/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.
cd utilities_root/bin directory
Run the utility, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name:

(Linux)
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 WebSphere 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 4

If your merchant key is stored in an external file and we want to change the value by -interactive parameter and store it to a different file, complete these steps:
Stop the WebSphere 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 detail descriptions of each parameter and the format of the key files.
cd utilities_root/bin directory
Run the utility, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name. Then, we are prompted to input the new merchant key.
(Linux)
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.
Related concepts
Key Locator Framework (KLF)

Related tasks
Run utilities from the Utility server Docker container
Update encrypted data using MigrateEncryptedInfo (server offline)
Update encrypted data using MigrateEncryptedInfo (server online)

Related reference
Optimize the MigrateEncryptedInfo utility