Troubleshoot and support > Payments > Troubleshooting: Payments
Changing Payments instance password and updating encrypted data using ChangePassword
The ChangePassword utility can change the value and location of the Payments instance password. It also updates the encrypted data in the Payments database.
Before you begin
It is strongly recommended to back up the following files before running the ChangePassword utility:
- The Payments instance.xml file in the WC_INSTALL/instances/payments_instance/xml directory.
- The PaymentsInstance.properties file in the WC_INSTALL/payments/instances/payments_instance directory.
- The server.xml file in the WC_PROFILE/config/cells/cellnodes/node_name/servers/payments_instance_Commerce_Payments_Server directory.
It is strongly recommended to back up the following tables in the Payments database before running the ChangePassword utility with the "-k" flag:
- ETKey
- ETBinaryData
- OfflineCardOrder (if it exists in the Payments database)
- BankServACHOrder (if it exists in the Payments database)
- VisaNetOrder (if it exists in the Payments database)
- PaymentechOrder (if it exists in the Payments database)
The ChangePassword utility can change the value and location of the Payments instance password. It will also update the encrypted data in the Payments database. Ensure that you have followed the back up recommendations before going on to run the ChangePassword utility.
Procedure
- If the Payments instance password is currently stored in the Payments instance.xml file, and you are not planning to move it to another location while changing its value, do the following steps:
- Stop the Payments instance.
- Stop Configuration Manager.
- Use the command line, switch to the WC_INSTALL/payments/bin directory.
- Run the ChangePassword utility...
ChangePassword payments_instance
- Enter the current password and the new password using the command line when prompted.
- If the Payments instance password is currently stored in the Payments instance.xml file, and to move it to another location while changing its value, do the following steps:
- Stop the Payments instance
- Stop Configuration Manager.
- If you are using the default keys configuration file WCKeys.xml in the WC_INSTALL/payments/xml/config directory, create a custom keys configuration file first because the default WCKeys.xml file is for IBM use only and should not be modified by customers, to avoid being overwritten during migration to later versions of WebSphere Commerce. Sample contents of the custom keys configuration file:
<?xml version="1.0" encoding="UTF-8"?> <keys> <key name="PaymentsInstancePassword" providerName="WC" status="current" className="com.ibm.commerce.security.keys.WCPaymentsInstancePasswordImpl"> </key> <key name="PaymentsInstancePassword" providerName="WC" status="new" 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>
All the external key files (including the key file, the key encryption key file, and the new key files) need to be manually created. The format of the key files is...
<?xml version="1.0" encoding="UTF-8"?> <keys> <key value="123abc" /> </keys>The key file can specify an empty value. The encrypted version of the new Payments instance password will be stored here after running the ChangePassword utility. The key encryption key needs to be specified in the key encryption key file as plain text. Two administrators each enters half of the Payments instance password as plain text in the two new key files.
- Add a KeysConfigFile attribute in the PMInstance section of the Payments instance XML file. The attribute points to the custom keys configuration file with a relative path to the Payments XML directory. By default, this XML directory is in the following location:
WC_INSTALL/instances/payments_instance/xmlFor example, this value might be KeysConfigFile="config/CustomKeys.xml"
- Use the command line, switch to the WC_INSTALL/payments/bin directory.
- Run the ChangePassword utility with "-k" flag: For example,
ChangePassword payments_instance -k
- Edit the keys configuration file. Remove the "current" key provider and mark the "new" one as "current".
- Start the Payments instance.
- If the Payments instance password is currently stored in an external file, and to change the value of the Payments instance password, do the following steps:
- Stop the Payments instance
- Stop Configuration Manager.
- Modify the custom keys configuration file. Sample contents of the custom keys configuration file:
<?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" /> </key> <key name="PaymentsInstancePassword" providerName="WC" status="new" 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>Two administrators will each enter half of the Payments instance password as plain text in newKeyFile1 and newKeyFile2 of the new key provider. A different key encryption key file can be specified for the new key provider. The current key provider does not have to specify newKeyFile1 and newKeyFile2, but it can. The format of the external key files (including the key file, the key encryption key file, and the new key files) is...
<?xml version="1.0" encoding="UTF-8"?> <keys> <key value="123abc" /> </keys>
- Add a KeysConfigFile attribute in the PMInstance section of the Payments instance XML file. The attribute points to the custom keys configuration file with a relative path to the Payments XML directory. By default, this XML directory is in the following location:
WC_INSTALL/instances/payments_instance/xmlFor example, this value might be KeysConfigFile="config/CustomKeys.xml"
- Use the command line, switch to the WC_INSTALL/payments/bin directory.
- Run the ChangePassword utility with "-k" flag.
ChangePassword <payments_instance> -k
- Two administrators will each enter half of the Payments instance password as plain text in newKeyFile1 and newKeyFile2 of the new key provider. A different key encryption key file can be specified for the new key provider. The current key provider does not have to specify newKeyFile1 and newKeyFile2, but it can. The format of the external key files (including the key file, the key encryption key file, and the new key files) is...
<?xml version="1.0" encoding="UTF-8"?> <keys> <key value="123abc" /> </keys>
- Start the Payments instance.