Updating encrypted data using MigrateEncryptedInfo (server online)

When the server is running, you can change the merchant key and update encrypted data with the MigrateEncryptedInfo utility. Use the Key Locator Framework (-k) option to specify the old and new keys to assign a version number to each key.

Note: To update encrypted data with the MigrateEncryptedInfo utility while the server is offline, see Updating encrypted data using MigrateEncryptedInfo (server offline).

Before you begin

The site must use a merchant key that is configured in the Key Locator Framework. That is, a custom key configuration file is already specified in wc-server.xml file.
Ensure that the user ID that runs the utility (wasuser) has full permission to access files and subfolders in the WC_installdir/instances/instance_name directory.
For Oracle 9i databases, set the UNDO table space to a sufficiently large size. From an SQLPlus prompt, enter the following command:
```
alter database datafile undotablespace datafile autoextend on
maxsize unlimited;
```

Procedure

Back up your database, following the instructions in your database engine documentation.
Prepare the new key files and the key configuration file.

Specify a new version for the new key that is different from the version that is used by the existing current key. Typically, the version is one higher than the version of the current key. Place the key configuration file in the following directory: WC_eardir/xml/config.
Deploy the changes to the custom XML files (For example, merchantKey_v2.xml, CustomKeys.xml, KeyEncryptionKey.xml, newMerchantKey_v2-1.xml, and newMerchantKey_v2-2.xml). For steps on deploying multiple files, see Deploying Java EE assets for a partial application. If you are deploying to a clustered environment, see the following step.

Note: After you save the updated file to the master configuration, the server is restarted.
Optional: If you are running in a clustered environment and cannot afford any downtime, you can use a two-step approach to register the new key. The first step is to use rollout update capability to register a "pending" key that all cluster members will recognize as an upcoming "new" key that is soon to become active. The rollout update capability allows these cluster members to use this key for decryption or validation purposes only. At this point, this "pending" key will not be used to encrypt any records that are to be inserted to the database. The second step is to use rollout update to change the "pending" key to the "new" status so that this key becomes the key to use for encryption on all new records.
Consider the following example:
A clustered environment is deployed with two servers. The two-step approach is complete. Assuming that cluster member one has the "new" key that is registered with a "new" status, while cluster member two still has it in the "pending" state. If a shopper registers in cluster member one, the password is encrypted with the "new" key. Assume that the shopper then logs off and logs on again. The second logon attempt gets routed to cluster member two, although in cluster member two, the "pending" key cannot be used for encrypting new records, this key is available for validations purpose. The shopper is logged on successfully.
The following are the details for this two-step process:
1. Specify a key with a status of "pending" in the custom key configuration file. Use the rollout update option to update the keys configuration.
```
<key name="MerchantKey" providerName="WC" status="pending" version="2" 
     className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
		     <config name="keyFile" value="merchantKey_v2.xml" />
		     <config name="newKeyFile1" value="newMerchantKey_v2-1.xml" />
		     <config name="newKeyFile2" value="newMerchantKey_v2-2.xml" />
	</key>
```
2. Monitor the progress by reviewing the node agent SystemOut.log. After the process is complete, use the same technique to change the pending key with a status of new and propagate to all cluster members.
```
<key name="MerchantKey" providerName="WC" status="new" version="2"
	      className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
		       <config name="keyFile" value="merchantKey_v2.xml" />
		       <config name="newKeyFile1" value="newMerchantKey_v2-1.xml" />
		       <config name="newKeyFile2" value="newMerchantKey_v2-2.xml" />
	</key>
```
When all the servers are updated with the new key registered:
- Log on using a Windows user ID with Administrator authority.
- Switch to the WebSphere Application Server user ID (for example, wasuser):
```
su - WC_non_root_user
```
For DB2 databases, open a DB2 command window. For Oracle databases, open a regular command window.
Switch to the WC_installdir\bin directory.
Run the MigrateEncryptedInfo utility by using the Keys Locator Framework (-k) option.
Ensure that you are aware of the following considerations when running the utility:
- 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 the steps in Example 2.
- If your merchant key is stored in an external file and you want to change the value, complete the steps inExample 3.
- 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 the steps in Example 4.
The MigrateEncryptedInfo tool generates the following log files:
- migrateFailedRecords_TABLENAME.log
- MKChangeUserAndCCInfoMigration.log
- MigrateEncryptedInfoError.log
in the following directory:
- WC_userdir/instances
- WC_installdir/logs
Review the information in these log files. Ensure that there are no error messages.