Reference > Utilities


MigrateEncryptedInfo utility

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:

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


Syntax


Parameter Values

database_type

Is the database type (db2 for DB2 databases).

database_type

Is the 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 the 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.

-interactive

Optional: The administrator is prompted for the new merchant key when this flag is specified.


Example 1

If the merchant key is currently stored in the instance.xml file and 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

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. Open a command prompt and navigate to the WC_INSTALL/bin directory

  3. Run the following command:

  4. Restart the WebSphere Commerce instance.


Example 2

If the merchant key is currently stored in the instance.xml file and to change the value and move it to an external file, do the following:

  1. Stop the WCS 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_EAR/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.

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

  3. Open a command prompt and navigate to the WC_INSTALL/bin directory

  4. 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_EAR/xml/config/CustomKeys.xml

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

    In clustered environments, move the configuration changes, that is, merchantKey.xml, CustomKeys.xml, and KeyEncryptionKey.xml to the other servers. This enables the other servers to locate the new merchant key during startup.

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

  7. Start the WebSphere Commerce instance.

  8. Run the following command:

  9. Restart the WebSphere Commerce instance.


Example 3

If the merchant key is currently stored in an external file and to change the value, do the following:

  1. Stop the WCS 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_EAR/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.

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

  3. Open a command prompt and navigate to the WC_INSTALL/bin directory

  4. 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_EAR/xml/config/CustomKeys.xml

  5. Start the WCS instance.

  6. Run the following command:

  7. Restart the WebSphere Commerce instance.


Example 4

If the merchant key is currently stored in an external file and to change the value and store it to a different file, do the following:

  1. Stop the WCS 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_EAR/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/merchantKey1.xml" />         <config name="keyEncryptionKeyFile"
            value="c:/WebSphere/CommerceServer/instances/demo/xml/KeyEncryptionKey1.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.

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

  3. Open a command prompt and navigate to the WC_INSTALL/bin directory

  4. 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_EAR/xml/config/CustomKeys.xml

  5. Use a secure removal tool (SDelete or SRM) to remove the old key files (e.g. merchantKey.xml and KeyEncryptionKey.xml).

  6. Start the WCS instance.

  7. Run the following command:

  8. Restart the WebSphere Commerce instance.


+

Search Tips   |   Advanced Search