Key Provider Implementations for merchant key

The most secure solution is to store the merchant key in a hardware device. A hardware solution takes care of matters such as secure storage and split knowledge of the merchant key. However, it is also possible to store an encryption key in a file, provided appropriate precautions are taken. Such precautions include the use of file permissions, file integrity monitoring, and file access auditing.

By default two encryption key providers for the merchant key are available. The first one, WCMerchantKeyImpl, is for retrieving the merchant key from the instance XML file. The second one, WCExternalFileMerchantKeyImpl, is for retrieving the merchant key from an external file.

WCMerchantKeyImpl

The default implementation, com.ibm.commerce.security.keys.WCMerchantKeyImpl, continues reading the merchant key from the instance.xml file. The implementation cannot be used to set the merchant key in the instance XML file. Therefore, WCMerchantKeyImpl cannot be used as the "new" key provider when running MigrateEncryptedInfo. It can be used as the "current" key provider, when changing to a different key provider.

This is the specification of this key provider in workspace_dir/WC/xml/config/WCKeys.xml:


<?xml version="1.0" encoding="UTF-8"?>
<keys>
<key name="MerchantKey" 
providerName="WC" 
status="current"
className="com.ibm.commerce.security.keys.WCMerchantKeyImpl"> 
</key>
</keys>

Notice that the definition does not specify the path of the Commerce+ Transaction Server configuration file. This is not a problem when used at run time because the current instance is known, so the appropriate instance's configuration file can be accessed. However, when the Key Locator Framework is used from a command-line script, for example, MigrateEncryptedInfo, the runtime environment is not initialized. Therefore, in a multi-instance scenario, we would not be able to find the correct instance's configuration file that is based on the above definition. Consequently, an extra config parameter, instanceName, is needed whenever WCMerchantKeyImpl is going to be used on the command line to specify the name of the instance. Using the instance name, we can find the correct Commerce+ Transaction Server configuration file to retrieve the merchant key.

For example, the keys configuration file for an instance named "demo":


<?xml version="1.0" encoding="UTF-8"?>
<keys>
<key name="MerchantKey" 
providerName="WC" 
status="current"
className="com.ibm.commerce.security.keys.WCMerchantKeyImpl">
<config name="instanceName" value="demo"/> 
</key>
</keys>

WCExternalFileMerchantKeyImpl

An implementation that helps to enable PCI compliance, com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl is used to read and store merchant key from an external file. Since the instance XML file contains a lot more information besides the merchant key, it is difficult to control access to the file. To comply with PCI standards, this key provider implementation reads the merchant key from an external file.

When a new merchant key is required, two administrators each enter half of the merchant key into two temporary external files. This is done in order to adhere to the split knowledge criteria. The name and location of these temporary files is specified in the keys configuration file. The keys in these external files are stored in plain text.

When it is time to update the merchant key file, WCKey.updateValue() is called to update the external file with the new encrypted merchant key value, and also clear the contents of the two temporary external files. As an added security measure, this provider allows the customer to specify an optional key encryption key. This key encryption key is used to encrypt the merchant key when storing the merchant key in the external file. If the key encryption key is not specified, then the internal encryption key is used.

The following shows the keys configuration file that registers the WCExternalFileMerchantKeyImpl provider.


<?xml version="1.0" encoding="UTF-8"?>
<keys>
<key name="MerchantKey" 
providerName="WC" status="new"
className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
<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>
</keys>

Where:

keyFile

The keyFile is where the current merchant key is stored, encrypted using the key encryption key. For a new key, the keyFile (For example, merchantKey.xml) must be created manually, with an empty key value: <key value="" />. When MigrateEncryptedInfo is run, the plain text key values from newKeyFile1 and newKeyFile2 are merged, encrypted, and then stored in merchantKey.xml.

keyEncryptionKeyFile

Optional: Specifies the file where the key encryption key is stored, in plain text. If this attribute is not specified, the default key encryption key is used. The key encryption key should be at least as strong as the merchant key (32 hexadecimal characters).

newKeyFile1

Required when the status of the key provider in the keys configuration file is "new". This value is the name of the file where the first half of the merchant key is stored in plain text. The content of the file is blanked out after the tool is complete and all temporary files are deleted.

newKeyFile2

Required when the status of the key provider in the keys configuration file is "new". This value is the name of the file where the second half of the merchant key is stored in plain text. The content of the file is blanked out after the tool is complete and all temporary files are deleted.

Note:

The keyFile, keyEncryptionKey, and the 2 new KeyFiles are in the following format:


<?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\key.xsd">
<key value="1234567890abcdef" />
</keys>

Either absolute or relative paths can be used for all of these config attributes. If relative path is used, it is relative to the location of the custom keys configuration file, CustomKeys.xml. In runtime environment, the location of the CustomKeys.xml is defined in the <Instance> section of instance XML file. For command-line utilities, the location of the CustomKeys.xml is passed in as command-line arguments.

status

Indicates if the key provider is active. The possible values are current and new.

A current value is indicative that the key provider is in use and active. The encrypted data in the database is encrypted with the key from this provider.

A new value indicates the key provider to be migrated to. This provider is used by the MigrateEncryptedInfo utility to migrate the encrypted data to this new key.