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.
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:
- 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>
- 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.
Review the information in these log files. Ensure that there are no error messages.