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 WC_eardir/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>
Changes to the key provider XML files should be deployed following the instructions in Deploying Java EE assets for a partial application.
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":
<?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 (eight hexadecimal digits) 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>
- 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 (16 or 32 lowercase hexidecimal digits).
- 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 (eight lowercase hexadecimal digits, if the merchant key is 16 digits) 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 (eight lowercase hexadecimal digits, if the merchant
key is 16 digits) 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 newKeyFiles 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="12344567890abcdef" /> </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.
- The keyFile, keyEncryptionKey, and the 2 newKeyFiles are in the following format:
- status
- Indicates if the key provider is active. The possible values are
current
andnew
.