MigrateEncryptedInfo utility

+

Search Tips   |   Advanced Search

MigrateEncryptedInfo is a utility for changing the merchant key and re-encrypt all encrypted data in the database. 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 using the "-k" parameter.

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

...in the following directory:

You should review the information in these log files and ensure they do not contain any error messages.

 

Syntax

 

Parameter Values

Linux| database_type

Is your database type (db2 for DB2 databases).

AIX|Solaris|Windows:

database_type

Is your database type, and is either db2 for DB2 databases or oracle for Oracle databases.

instance

Is a mandatory parameter for the name of the instance which will be updated.

num_of_threads

The number of threads that are spawned to re-encrypt the data. The recommendation is that this number should match the number of processors on the server running the utility.

commit_count

The number of records that will be processed before the transaction is committed.  The commit_count should be set to the maximum number of transactions that your database transaction log will allow. 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 will detect that you are using the default key.

new_merchant_key

A required parameter that should be specified if you are currently using the default merchant key. If you are already using a non-default merchant key, then this parameter is optional. This parameter should be in clear text (ASCII) form. 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.

  • 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 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 four consecutive characters.

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.

 

Example 1

If your merchant key is currently stored in the instance.xml file and you want to change the value without moving the another location, run the utility as follows, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name:
MigrateEncryptedInfo db2 demo 1234567890abcdef abcdef1234567890

MigrateEncryptedInfo db2 demo 4 5000 1234567890abcdef abcdef1234567890
I5/OS:

Windows:

The WebSphere Commerce version 6.0.0.5 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:

  1. Start the WebSphere Commerce instance.

  2. Run the following command:

  3. Restart your WebSphere Commerce instance.

 

Example 2

If your merchant key is currently stored in the instance.xml file and you want to change the value and move it to an external file...

  1. Stop the WebSphere Commerce instance.

  2. 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 classpath 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>

    Please refer to the Key Provider Implementations for merchant key for detail descriptions of each parameter and the format of the key files.

  3. Run the utility, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name
    MigrateEncryptedInfo db2 demo -k WC_eardir/xml/config/CustomKeys.xml

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

  4. 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"

  5. 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" encryption key provider

    • Change the status of the "new" key provider to "current".

  6. Start the WebSphere Commerce instance.

  7. Run the following command:

  8. Restart your WebSphere Commerce instance.

 

Example 3

If your merchant key is currently stored in an external file and you want to change the value...

  1. Stop the WebSphere Commerce instance.

  2. Start the WebSphere Commerce instance.

  3. 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 classpath 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.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>

    Please refer to the Key Provider Implementations for merchant key for detail descriptions of each parameter and the format of the key files.

  4. Run the utility, assuming the encrypted data is stored in a DB2 database and "demo" is the instance name
    MigrateEncryptedInfo db2 demo -k WC_eardir/xml/config/CustomKeys.xml

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

  5. Run the following command:

  6. Restart your WebSphere Commerce instance.

Related concepts

Key Locator Framework (KLF)

Related tasks

Updating encrypted data using MigrateEncryptedInfo


Related Reference

Optimizing the MigrateEncryptedInfo utility