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:

Notice that the definition does not specify the path of the WebSphere Commerce 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 WebSphere Commerce configuration file to retrieve the merchant key.

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

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.

Where:


Related concepts
Implementation of the KLF