Implementation of the KLF

If you want to retrieve the merchant key from a medium other than the WebSphere Commerce configuration file, you must define the key providers in a separate custom key configuration file that is called, for example, CustomKeys.xml. Once you define this file, to make the external merchant key available to the WebSphere Commerce runtime, you must add the KeysConfigFile attribute, which is specified in the <Instance> section of the WebSphere Commerce configuration file. By defining this attribute, the Key Locator Framework (KLF) retrieves the merchant key using the key provider that is specified in the CustomKeys.xml instead of retrieving it from the WebSphere Commerce configuration file.

The value of the KeysConfigFile attribute is the location of the CustomKeys.xml relative to a path specified in the class path of the WebSphere Commerce application. When WebSphere Commerce runtime reads this attribute from the WebSphere Commerce configuration file, it loads the custom keys configuration file as a resource from the class path.

For example, if you deploy the CustomKeys.xml file in the WC_eardir/xml/config/ directory, since WC_eardir/xml/ directory is on the default class path of WebSphere Commerce application, you specify the following attribute in the WebSphere Commerce configuration file:


KeysConfigFile = "config/CustomKeys.xml"

Note: Only a forward slash (/) can be used to specify the path to the key file within the KeysConfigFile attribute.

If the KeysConfigFile attribute is not present in the WebSphere Commerce configuration file, the WebSphere Commerce runtime environment loads the configuration file from the following hardcoded location: WC_eardir/xml/config/WCKeys.xml

The CustomKeys.xml file itself should be deployed following the instructions in Deploying Java EE assets for a partial application.

The default WCKeys.xml applies to all instances. This default WCKeys.xml file contains a WCMerchantKeyImpl provider, which continues to read the merchant key from the file.

If you want to store the merchant key in another location, such as within an external file or hardware device, you must add the KeysConfigFile attribute to the WebSphere Commerce configuration file. Adding the attribute to the WebSphere Commerce configuration file specifies the location of the merchant key relative to the class path of the WebSphere Commerce application. The new merchant key file registers the key provider class, which manages the merchant key that is stored in the new location.

For an example of the default WCKeys.xml configuration file, and a description of its contents, see Key Locator Framework (KLF).

An example of a CustomKeys.xml would appear as follows:


<key name="MerchantKey"
		providerName="WC"
		status="current"
		className="com.ibm.commerce.security.keys.MyMerchantKeyImpl"
		version="3"
		algorithm="AES">

		<config name="param1" value="value1"/>
		<config name="param2" value="value2"/>
</key>

<key name="SessionKey" 
        providerName="WC" 
        status="current"
        className="com.ibm.commerce.security.keys.WCSessionKeyImpl">
</key>

Note: The default session key provider must be defined in your CustomKeys.xml. The KLF does not support defining a custom session key implementation.