Migrating encrypted data

When migrating IBM Websphere Commerce Version 8 to HCL Commerce Version 9.0 you must migrate your encrypted data. Previous versions of WebSphere Commerce allowed for your site to use 3DES (16bit merchantKey) or AES (32bit merchantKey) encryption. In HCL Commerce Version 9.0, only AES encryption is used.

Note: This procedure is only required if your original IBM Websphere Commerce Version 8 installation is configured to use 3DES encryption for the database. This is the case when AES_DB is set to false in the HCL Commerce wc-server.xml configuration file, or not specified at all.

Before you begin

Stand up or log in to the required environment.

1. Log in to the environment that is hosting the Utility server Docker container.
  If a Utility server Docker container is not deployed, see Preparing a Docker host server to launch Utility server Docker container.
2. Enter the Utility server Docker container.
  For example,
```
docker exec -it utility_container_name bash
```
  You are now within the Utility server Docker container. The following steps must be performed in this environment.

Procedure

Create the required files to migrate your encrypted data.
1. Create Product.xml.
  Product.xml is used to specify what type of encryption is used in both the database and for files on your IBM Websphere Commerce Version 8 environment.
```
<security>
  <AES_Files>true</AES_Files>
  <AES_DB>false</AES_DB>
</security>
```
  In this example, AES is specified as being used for files, but not for the database. The default encryption algorithm for the database is therefore assumed (3DES).
  Note: After running the migrateEncryptedInfo utility against your database, both must be set to true.
2. Update the HCL Commerce configuration file (wc-server.xml).
  Ensure that the same information is specified in the wc-server.xml configuration file.
```
AES_DB="false"
AES_Files="true"
```
  Note: After running the migrateEncryptedInfo utility against your database:
  - Both AES_DB and AES_Files must be set to true.
  - Within the <Database> element, update the DBUserPwd to the AES encrypted value using the wcs_encrypt.sh utility.
    wcs_encrypt.sh password
  - For more information about the wc-server.xml configuration file, see HCL Commerce configuration file (wc-server.xml).
3. Optional: Create KeyEncryptionKey.xml.
  
  The keyEncryptionKey adds an additional level of security when encrypting the merchantKey. The value that it contains is a 32 character string.
  
  The keyEncryptionKey value can be any combination of the following alphanumeric characters: abcdef0123456789.
  
  For example: abcdef0123456789abcdef0123456789.
Configure the data encryption migration.
Create CustomKeys.xml. This file is used to give the MigrateEncryptedInfo utility the instructions on what to migrate data from and to.
Place this file at the following location: /opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/CustomKeys.xml.
A sample configuration file is as follows:
```
<?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 xsd/WCKeys.xsd">
		
    <key name="MerchantKey" providerName="WC" status="current"
     className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl" algorithm="3DES">
	<config name="keyFile" value="oldMerchantKey.xml"/>
    </key>

    <key name="MerchantKey" providerName="WC" status="new"
     className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl" algorithm="AES">
	<config name="keyFile" value="merchantKey.xml"/>
	<config name="keyEncryptionKeyFile" value="KeyEncryptionKey.xml"/>
	<config name="newKeyFile1" value="newMerchantKey1.xml"/>
	<config name="newKeyFile2" value="newMerchantKey2.xml"/>
     </key>
		
     <key name="SessionKey" providerName="WC" status="current"
	className="com.ibm.commerce.security.keys.WCSessionKeyImpl">
     </key>
  </keys>
```
In the customKeys.xml there are three <key> elements:
1. The first key designates the MerchantKey that your data is currently encrypted with. This is your current key, and is specified in this configuration file with the status value of current.
  This is used by the utility to determine how the data is currently encrypted, and what to use to decrypt the data for the transition to a new key and/or encryption algorithm.
  This key will become obsolete once the utility is run successfully and can be deleted.
2. The second key designates the MerchantKey that you want to use with your site going forward. This is known as your new key, and is denoted in this configuration file with the status value new.
  This is the key that you are transitioning to using. It is used by the utility to re-encrypt the data that is decrypted by the original (presently current) key.
  Once the utility is run, this key is now the current key. It will take the place of the original current key (the first key value that is specified in the configuration file, with a status of current) for any future encryption algorithm or key migration.
3. The third key denotes your sessionKey and is not important to the MigrateEncryptedInfo utility.
To specify the configuration of the utility, update this file accordingly:
1. Specify the algorithm used by your current key, and new key.
  This is achieved by specifying the algorithm element for each key to 3DES or AES accordingly.
2. Specify the current key (oldMerchantKey.xml).
  In the example above, the current key is specified as being contained within oldMerchantKey.xml. This file will contain the merchantKey value from your IBM Websphere Commerce Version 8 installation.
  If you were not using KLF in Version 8, the encrypted merchant key is contained within wc-server.xml of your IBM Websphere Commerce Version 8 installation.
  You must now encrypt the old merchant key using AES. To encrypt this value with AES, use the wcs_encrypt.sh utility.
```
wcs_encrypt.sh password
```
  The generated AES encrypted string is the value that should be entered into oldMerchantKey.xml.
  For example, if your unencrypted merchantKey is abcdef0123456789, the utility will produce the AES encrypted string value of 000ITx0jBS3xHdvCq2EJXzDhtd9o3cRAEo/5eoVZy9vl+O2yV1SDG/iSURev3mc.
  This value is then placed within oldMerchantKey.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 xsd/key.xsd">
    <key value="000ITx0jBS3xHdvCq2EJXzDhtd9o3cRAEo/5eoVZy+9vl+O2yV1SDG/iSURev3mc"/>
  </keys>
```
3. Specify the new key (newMerchantKey1.xml / newMerchantKey2.xml).
  Both of these files will contain 16 bits of the new 32 bit unencrypted merchantKey value. Meaning newMerchantKey1.xml will contain the first 16 and newMerchantKey2.xml will contain the second 16 characters.
  Each key value can be any combination of the following alphanumeric characters: abcdef0123456789.
  Place these key files at the following location:
  - /opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/newMerchantKey1.xml
  - /opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/newMerchantKey2.xml
    A sample key file is as follows:
    <?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 xsd/key.xsd"> <key value="abcdef0123456789"/> </keys>
    Note: Both newMerchantKey1.xml and newMerchantKey2.xml are deleted when running the migrateEncryptedInfo utility. If you experience a failure, or if you need to re-run migrateEncryptedInfo, then these files mist be recreated.
Complete the data encryption migration.
Migrate your data encryption using the migrateEncryptedInfo utility.
Note: If you have already run the migrateEncryptedInfo utility, you must clear the existing merchantKey value before re-running the migrateEncryptedInfo utility.
An example of running this utility successfully is as follows:
```
[root@utils /]# /opt/WebSphere/CommerceServer90/bin/MigrateEncryptedInfo.sh db2 demo 1 1 -k /opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/CustomKeys.xml

Migration completed. Please check /opt/WebSphere/CommerceServer90/logs/MigrateEncryptedInfoError.log for any errors. Some errors can be ignored; see documentation for details.
```
The migrateEncryptedInfo utility generates a newly encrypted merchant key file, merchantKey.xml.
Ensure that the data encryption migration completed successfully.
Check the MigrateEncryptedInfoError.log and CCInfoMigration.log log files to determine if there were any errors encountered by the utility.
Update your HCL Commerce Version 9.0 installation to use AES encryption.
1. Update wc-server.xml. Set AES_DB="true".
2. Update product.xml. Set <AES_DB>true<AES_DB/>.
3. Make the merchant key accessible to your environment.
  - If you plan to use a custom Key Locator Framework (KLF) file. For example, CustomKeys.xml.
    1. Update your site configuration.
      
      Open the wc-server.xml configuration file for editing.
      
      Add the following within the <Instance> section:
      KeysConfigFile = "config/CustomKeys.xml"
      
      Save and close the file.
    2. Define CustomKeys.xml as follows:
      <?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 xsd/WCKeys.xsd"> <key name="MerchantKey" providerName="WC" status="current" className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl" algorithm="AES"> <config name="keyFile" value="merchantKey.xml"/> <config name="keyEncryptionKeyFile" value="KeyEncryptionKey.xml"/> </key> <key name="SessionKey" providerName="WC" status="current" className="com.ibm.commerce.security.keys.WCSessionKeyImpl"> </key> </keys>
      Note: Only use keyEncryptionKeyFile if you re-encrypted your merchantKey using this file.
  - If you do not plan to use a custom KLF file, for example, CustomKeys.xml, and you plan to store the merchant key in Vault:
    1. Obtain the new encrypted merchant key from the generated merchantKey.xml file and then store it in Vault. See, Key Locator Framework (KLF).
    2. If you encrypted the merchant key with a key encryption key, obtain the new key encryption key from the KeyEncryptionKey.xml file, and store it in Vault.
  - If you do not plan to use a custom KLF file, for example, CustomKeys.xml, and you do not plan to use Vault to store the merchant key:
    As per WCKeys.xml, then the encrypted merchantKey value must be stored in merchantKey.xml, and the key encryption key must be stored in KeyEncryptionKey.xml.
4. If you are planning to use a custom Keys Configuration File, for example, CustomKeys.xml, then deploy any modified files to your Transaction server (ts-app).
  For example, wc-server.xml, CustomKeys.xml, merchantKey.xml, and KeyEncryptionKey.xml.
5. If your Transaction server is running, restart the application.

Results

Your data encryption is migrated from your old encryption algorithm and merchant key, to the newly specified encryption algorithm and merchant key.