Key Provider Implementations for Payments instance password

The most secure solution is to store the Payments instance password 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, only if appropriate file permissions are in place, file integrity monitoring is in place, and access to the file is audited.

Note: The Payment instance that is referred to here is the deprecated WebSphere Commerce Multipayment Framework.

WCPaymentsInstancePasswordImpl

The default implementation, com.ibm.commerce.security.keys.WCPaymentsInstancePasswordImpl, continues reading the Payments instance password from the Payments instance XML file. The implementation cannot be used to set the Payments instance password in the Payments instance XML file. Therefore, WCPaymentsInstancePasswordImpl cannot be used as the "new" key provider when you are running the ChangePassword utility. It can be used as the "current" key provider, when you are changing to a different key provider.

This is the specification of WC_installdir\payments\xml\config\WCKeys.xml when you apply the APAR:


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

</key>
</keys>

WCExternalFilePaymentsInstancePasswordImpl

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

The following is an example of Payments keys configuration file that is in the WC_installdir/instances/ payments_instance_name/xml directory:


<?xml version="1.0" encoding="UTF-8"?>
<keys>
<key name="PaymentsInstancePassword" 
providerName="WC" 
status="current"
className="com.ibm.commerce.security.keys.WCExternalFilePaymentsInstancePasswordImpl">
<config name="keyFile" value="InstancePassword.xml"/>
<config name="keyEncryptionKeyFile"
value="keyEncryptionKey.xml"/>
<config name="newKeyFile1" value="newInstancePassword1.xml"/>
<config name="newKeyFile2" value="newInstancePassword2.xml"/>
</key>
</keys>

Where:

keyFile: File where the Payments instance password is stored, encrypted using the key encryption key.
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 must be a 16-bytes hexadecimal digits.
newKeyFile1: (Optional) Needed when status = "new". File where the first half of the Payments instance password is stored in plain text.
newKeyFile2: (Optional) Needed when status = "new". File where the second half of the Payments instance password is stored in plain text.

Note: Any of these config parameters' value can specify an absolute path or a relative path to the keys configuration file. Relative paths are recommended.

When the status of the key provider is "current", the Payments instance password is read from the key file and decrypted using the key encryption key.

When a new Payments instance password is required, the status of the key provider must be "new". To adhere to the split knowledge criteria, two administrators each enter half of the Payments instance password as plain text in two temporary external files. The name and location of these temporary files is specified in the keys configuration file. Note: The new Payments instance password must have a minimum length of 8 bytes. Ensure that the password contains at least one numeric character and one alphabetic character. The password must not contain four consecutive occurrences of a character. The password must not contain more than four occurrences of a character.

As an extra security measure, this provider also uses a customer specified key encryption key, used to encrypt the Payments instance password, because the Payments instance password is stored in an encrypted format. The key encryption key is stored separately from the instance password key file in a plain-text, XML file. The two halves of the new instance password are read and combined into the whole one. It is then encrypted using the key encryption key and stored into the key file. At the same time, the contents of the two temporary external files are cleared.