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 MigrateEncryptedInfo utility more efficiently, it is recommended to 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.

Note: You can encounter a NullPointerException error when re-encrypting user passwords.

To correct this issue:

Open the following file for editing:
- WCDE_installdir\schema\db2\migration\DBUpdate.txt
- WC_installdir/schema/db2/migration/DBUpdate.txt
Remove USERS_ID from TableColumns for TableName USERREG.
For example, remove the following from the file:
```
TableName=USERREG

TableColumns=USERS_ID,LOGONPASSWORD,SALT,CHALLENGEANSWER
```

The MigrateEncryptedInfo utility is in the following directory:

WC_installdir/bin/MigrateEncryptedInfo.sh
WC_installdir/bin/MigrateEncryptedInfo.sh
WC_installdir/bin/MigrateEncryptedInfo.bat
WCDE_installdir/bin

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

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

in the following directory:

WC_userdir/instances
WC_installdir/logs
WCDE_installdir/logs

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

WebSphere Commerce Version 7.0.0.3 If the error happened during the data decryption or encryption, the related failed data records are recorded in the log file WC_installdir/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 WC_installdir/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 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:

If Feature Pack 3 is enabled and key versioning feature is used, the MigrateEncryptedInfo utility can be run again directly without restoring the database.
Restore the database first and run the utility again.

Syntax

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

Diagram showing the MigrateEncryptedInfo utility for Fix Pack 1. Parameters are described in the following list.

Parameter values

database_type

Linux Is your database type (db2 for DB2 databases).

Solaris AIX Windows Is your database type (db2 for DB2 databases or oracle for Oracle databases).

WebSphere Commerce Version 7.0.0.8 WebSphere Commerce Developer Is your database type (db2 for DB2 databases or oracle for Oracle databases or cloudscape for Apache Derby databases).

instance_name

Is a mandatory parameter for the name of the instance that is updated.

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_key parameter. If you are currently using the default WebSphere Commerce Suite 5.1 merchant key, do not specify this parameter. The utility detects that you are using the default key.

new_merchant_key

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

Its length must be 16 hexadecimal characters. Characters can be one of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, a, b, c, d, e, or f.
A 32 hexadecimal character is also supported. Characters can be one of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, a, b, c, d, e, or f.
It must contain a minimum of one alphabetic character.
It must contain a minimum of one numeric character.
It must be in lowercase.
It cannot contain more than 4 identical consecutive characters.
For example, aaaa1aaaa1aaaa12 and abcdeaaaa3aaaa12 are allowed. However, aaaaabaaaa1aaaa1 is not allowed as it is greater than 16 characters in length and contains more than 4 identical consecutive characters.
The key can now be either 16 or 32 characters in length. For example, aaaa1aaaa1aaaa12 and aaaa1aaaa1aaaa12aaaa1aaaa1aaaa12 are allowed.

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 the instance.xml file and you 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 1234567890abcdef abcdef1234567890

Note: This example is setting the num_of_threads value to 4 (for a 4-processor server) and the commit_count to 5000.

Then do the following steps:

Start the WebSphere Commerce instance.
Open a command prompt and navigate to the WC_installdir/bin directory
Run the following command:
- WC_installdir/bin/config_ant.sh -DinstanceName= instance_name UpdateEAR
- WC_installdir/bin/config_ant.bat -DinstanceName= instance_name UpdateEAR
Restart your WebSphere Commerce instance.

Example 2

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

Stop the WebSphere Commerce instance.

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, WC_eardir/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

C:\WebSphere\CommerceServer\wc.ear\xml\config\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="c:/WebSphere/CommerceServer/instances/demo/xml/merchantKey.xml"
/>
<config name="keyEncryptionKeyFile"
value="c:/WebSphere/CommerceServer/instances/demo/xml/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.

Note: The CustomKeys.xml and all other key files (for example, newMerchantKey1.xml) must be read and write accessible by wasuser.

Open a command prompt and navigate to the WC_installdir/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 WC_eardir/xml/config/CustomKeys.xml

MigrateEncryptedInfo db2 demo 4 5000 -k WC_eardir\xml\config\CustomKeys.xml

Add a KeysConfigFile attribute in the <Instance> section of the instance.xml file. This attribute points to an entry on the classpath of the WebSphere Commerce application. For example,
```
KeysConfigFile = "config/CustomKeys.xml"
```
Remove the old MerchantKey attribute and value references from the <Instance> section of the instance.xml and wc-server.xml configuration files. The KeysConfigFile attribute is now referred to for the generated merchantKey after running the MigrateEncryptedInfo utility.
Now that all the encrypted data is encrypted with the value retrieved from the "new" key provider, WCExternalFileMerchantKeyImpl, edit the keys configuration file as follows:
- Remove the "current" key provider.
- Change the status of the "new" key provider to "current".
Start the WebSphere Commerce instance.
Run the following command to deploy the changes made to instance.xml:
- WC_installdir/bin/config_ant.sh -DinstanceName= instance_name UpdateEAR
- WC_installdir/bin/config_ant.bat -DinstanceName= instance_name UpdateEAR
Deploy the changes to the custom XML files. For example, merchantKey.xml, CustomKeys.xml, and KeyEncryptionKey.xml. For steps on deploying multiple files, see Deploying Java EE assets for a partial application.
Note: In clustered environments, if any of your changed custom XML files are outside the EAR, for example merchantKey.xml and KeyEncryptionKey.xml, you must manually copy these files to the other servers.
Restart your WebSphere Commerce instance.

Example 3

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

Stop the WebSphere Commerce instance.

Modify your existing custom keys configuration file (For example, WC_eardir/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

C:\WebSphere\CommerceServer\wc.ear\xml\config\xsd\WCKeys.xsd">
<key name="MerchantKey" 
providerName="WC" 
status="current"
className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
<config name="keyFile"
value="c:/WebSphere/CommerceServer/instances/demo/xml/merchantKey.xml"
/>
<config name="keyEncryptionKeyFile"
value="c:/WebSphere/CommerceServer/instances/demo/xml/KeyEncryptionKey.xml"/>
</key>

<key name="MerchantKey" 
providerName="WC" 
status="new"
className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
<config name="keyFile"
value="c:/WebSphere/CommerceServer/instances/demo/xml/merchantKey.xml"
/>
<config name="keyEncryptionKeyFile"
value="c:/WebSphere/CommerceServer/instances/demo/xml/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.

Note: The CustomKeys.xml and all other key files (for example, newMerchantKey1.xml) must be read and write accessible by wasuser.

Open a command prompt and navigate to the WC_installdir/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 WC_eardir/xml/config/CustomKeys.xml

MigrateEncryptedInfo db2 demo 4 5000 -k WC_eardir\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 to the custom XML files. For example, merchantKey.xml, CustomKeys.xml, and KeyEncryptionKey.xml. For steps on deploying multiple files, see Deploying Java EE assets for a partial application.
Note: In clustered environments, if any of your changed custom XML files are outside the EAR, for example merchantKey.xml and KeyEncryptionKey.xml, you must manually copy these files to the other servers.
Restart your WebSphere Commerce instance.

Example 4

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 WebSphere Commerce instance.

Modify your existing custom keys configuration file (For example, WC_eardir/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 C:\WebSphere\CommerceServer\wc.ear\xml\config\xsd\WCKeys.xsd">
	<key name="MerchantKey" providerName="WC" status="current"
		className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
		<config name="keyFile"
			value="c:/WebSphere/CommerceServer/instances/demo/xml/merchantKey.xml" />
		<config name="keyEncryptionKeyFile"
			value="c:/WebSphere/CommerceServer/instances/demo/xml/KeyEncryptionKey.xml" />
	</key>

	<key name="MerchantKey" providerName="WC" status="new"
		className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
		<config name="keyFile"
			value="c:/WebSphere/CommerceServer/instances/demo/xml/merchantKey1.xml" />
		<config name="keyEncryptionKeyFile"
			value="c:/WebSphere/CommerceServer/instances/demo/xml/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.

Note: The CustomKeys.xml and all other key files (for example, newMerchantKey1.xml) must be read and write accessible by wasuser.

Open a command prompt and navigate to the WC_installdir/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 WC_eardir/xml/config/CustomKeys.xml
```
- ```
MigrateEncryptedInfo db2 demo 4 5000 -k WC_eardir\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).
Start the WebSphere Commerce instance.
Deploy the changes to the custom XML files. For example, merchantKey.xml, CustomKeys.xml, and KeyEncryptionKey.xml. For steps on deploying multiple files, see Deploying Java EE assets for a partial application.
Note: In clustered environments, if any of your changed custom XML files are outside the EAR, for example merchantKey.xml and KeyEncryptionKey.xml, you must manually copy these files to the other servers.
Restart your WebSphere Commerce instance.