Migrating from Triple DES to AES-128 encryption

Upgrade your default WebSphere Commerce database encryption to a stronger standard to reduce the chances of a successful brute force attack.

About this task

By default, the WebSphere Commerce database is encrypted using a Triple Data Encryption algorithm Standard (Triple DES) encryption algorithm. This standard was implemented at a time when a smaller cipher size was considered safe. While still considered a relevant industry standard, Triple DES has since been superseded with a stronger standard known as Advanced Encryption Standard (AES). With a stronger cipher standard, AES is less susceptible to brute force attacks that have become feasible with the continual improvements in computational power over the years.

Upgrading to AES-128 is part of updating to NIST SP 800-131A security standards. Consider NIST SP 800-131A for more enhancements to site security. See, Updating to NIST SP 800-131A security standards.

Procedure

Migrate encrypted data in the database to use AES 128-bit encryption. To complete this migration, you must run MigrateEncryptedInfo using the Key Locator Framework (-k) to specify the new AES merchant key. Add the algorithm="AES" attribute to the new key definition in the custom key configuration file. Use 32 hex characters (128 bits) for the new key and optional key encryption key values.

Note: Switching to an AES merchant key can result in temporary session cookie decryption errors for any existing sessions that were created before migrating to the AES merchant key.
1. Specify that the new key in the keys configuration file is using AES algorithm by adding algorithm="AES" attribute to the new key definition in the custom keys configuration file.
  For example, create or update the WC_eardir/xml/config/CustomKeys.xml file to have a new key definition like the following:
```
<key name="MerchantKey" providerName="WC" status="new" 
className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl" version="2" 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>
```
  For more information about the Key Locator Framework, see Key Locator Framework (KLF).
2. Ensure that the new keys files combine to form 32 hex characters.
3. Ensure that the optional key encryption key, if specified, is also 32 hex characters.
4. Open a command prompt and navigate to the following directory:
  - WC_installdir\bin
  - WCDE_installdir\bin
5. Run the MigrateEncryptedInfo utility for each instance, with the Key Locator Framework (-k) option:
  - For runtime environments, you can run the MigrateEncryptedInfo utility when the server is offline or online. Follow the steps in Updating encrypted data using MigrateEncryptedInfo (server offline) or Updating encrypted data using MigrateEncryptedInfo (server online)
  - For a development environment, you must run the MigrateEncryptedInfo utility when the server is offline. Follow the steps in Updating encrypted data using MigrateEncryptedInfo (server offline).
Update the Business Audit Key that is defined in BusinessAuditDataCapture.xml so it can be used with AES. The default audit key is an encrypted 16 character audit key. To encrypt with AES, the key must be replaced by the encrypted value of a new default 32 character audit key.
1. Navigate to the following directory:
  - WC_installdir\wc.ear\xml\config
  - workspace_dir\WC\xml\config
2. Open BusinessAuditDataCapture.xml for editing.
3. Optional: If you modified the default audit key to a custom value, rename the original AuditKey to be "CustomAuditKey".
  The CustomAuditKey node must be defined to continue validating existing records/signatures in the database.
  1. Search for the default audit key value: <AuditKey value="rZ15ws0ely9yHk3zCs3sTMv/ho8fY17s" />
  2. If the value matches your search, then you do not have to rename to CustomAuditKey. Continue to 2.d.
  3. If the value does not match your search, copy the <AuditKey> node.
  4. Paste the node into the file.
  5. For the node that you pasted, replace the word "AuditKey" with "CustomAuditKey".
4. Update the <AuditKey> node with the following 32 character audit key:
```
<AuditKey value="Jmz6ON1Y+573xkNVuOPbfRhZLEJTcW0kqgbCVJv4Jv7UlAGSVFHw6g=="/>
```
5. Save and close the file.
6. Deploy this file for each production instance. For steps on how to deploy a single file, see Deploying J2EE assets for a single file.
Update the instance configuration file, for each instance, to include the AES_DB="true" parameter.
1. In a text editor, open the WebSphere Commerce configuration file for the instance:
  - WC_installdir\instances\instanceName\xml\instance_name.xml
  - WCDE_installdir\workspace\WC\xml\config\wc-server.xml
2. In the configuration file, search for the parameter AES_DB. If the parameter does not exist, add the parameter.
  For example:
```
<config>
   <InstanceProperties name="Instance Properties">
		...	
  <Security AES_DB="true"
            AdminPwd="0gYsW5onfbvbp7Q3MYrc917pU0EFWcJPgwsgCjE/Btg="
            AdminUser="configadmin" AuthMode="" Realm="" RunAsID=""
            RunAsPwd="" enabled="false" enabledGlobal="true" passwordpolicy="true"/>
		...
    </InstanceProperties>
    ...
</config>
```
  If the parameter exists, ensure that the value is set to "true".
3. Save and close the file.
4. If your site uses a clustered environment, you must manually sync the nodes using the deployment manager for the changes to take effect.
5. Propagate the changes that are made to the WebSphere Commerce configuration file. For steps on how to propagate changes, see Propagating changes to the WebSphere Commerce configuration file.
Update product.xml to include the AES_DB="true" parameter.
1. Open WC_installdir\xml\product.xml
2. Search for the parameter, AES_DB. If the parameter does not exist, add the parameter.
  For example:
```
<websphere>
	<commercesuite>
		...
		<security>
			<AES_DB>true</AES_DB>
		</security>
	</commercesuite>
</websphere>
```
  If the parameter exists, ensure that the value is set to "true".
Restart the server.
Run the MigrateEncryptedFiles utility.
For the utility to complete successfully, ensure that the WebSphere Application Server is continuously up and running during the process.
1. In a command prompt, navigate to the following directory:
  - WC_installdir/bin
  - WC_installdir\bin
  - WCDE_installdir\bin
2. Execute the following command:
  - MigrateEncryptedFiles.sh
  - MigrateEncryptedFiles.bat
  - MigrateEncryptedFiles.bat
  To verify that the utility ran successfully, in each of the wc-server.xml or product.xml files that you updated in step 3 and step 4, ensure that the AES_FILES parameter is set to "true".
Restart the WebSphere Application Server.
Optional: If you are using WebSphere Commerce Search and Solr Application Security is enabled, update the Search administrative user's password that is stored in the namespace bindings in WebSphere Application Server to use AES encryption. See Securing the Websphere Commerce Search Server for instructions.