Secure > Enhance site security > Initialize KLF in WebSphere Commerce > Key Locator Framework (KLF)


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, as long as proper file permissions are in place, file integrity monitoring is in place, and access to the file is audited.

Out of the box, two encryption key providers for the merchant key are available. The first one, WCMerchantKeyImpl, is for retrieving the merchant key from the instance XMLfile. 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, MerchantKeyImpl 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_EAR/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.MerchantKeyImpl"> 
</key>
</keys>

Changes to the key provider XML files should be deployed following the instructions in Deploying J2EE 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, so in a multi-instance scenario, we would not be able to find the correct instance's configuration file based on the above definition. Therefore, an extra config parameter, instanceName, is needed whenever MerchantKeyImpl 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.MerchantKeyImpl">
<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. In order to comply with PCI standards, this key provider implementation will read and store the merchant key from an external file.

When a new merchant key is required, in order to adhere to the split knowledge criteria, two administrators will each enter half of the merchant key (eight hexadecimal digits) in two temporary external files. The name and location of these temporary files is specified in the keys configuration file. The keys in these external files will be stored in plain text.

When it is time to update the merchant key file, WCKey.updateValue() will be 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 extra security measure, this provider will also use a customer specified key encryption key, used to encrypt the merchant key, because the merchant key is stored in an encrypted format. The key encryption key will be stored separately from the merchant key file in a plain-text, XML file. The location of the key encryption key fill will be specified in the keys configuration file.

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="c:/WebSphere/CommerceServer/instances/demo/xml/merchantKey.xml"
/>
<config name="keyEncryptionKeyFile" 
value="c:/WebSphere/CommerceServer/instances/demo/xml/KeyEncryptionKey.xml"/>
<config name="newKeyFile1" value="c:/temp/newMerchantKey1.xml"
/>
<config name="newKeyFile2" value="c:/temp/newMerchantKey2.xml"
/>
</key>
</keys>

Where:

keyFile

File where the merchant key will be stored, encrypted using the key encryption key.

keyFile is a file which must be created manually. It is not generated by MigrateEncryptedInfo.

keyEncryptionKeyFile

(Optional) Specifies the file where the key encryption key will be stored, in plain text. If this attribute is not specified, the default key encryption key will be used. The key encryption key must be a 16 bytes hexadecimal digits.

newKeyFile1

Required when the status of the key provider in the keys configuration file is "new". This is the name of the file where the first half (8 hexadecimal digits) of the merchant key will be stored in plain text.

newKeyFile2

Required when the status of the key provider in the keys configuration file is "new". This is the name of the file where the second half (8 hexadecimal digits) of the merchant key will be stored in plain text.

  • 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.

status

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

A current value indicates 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.


+

Search Tips   |   Advanced Search