Deprecated feature

Changing Payments instance password and updating encrypted data using ChangePassword

The ChangePassword utility can change the value and location of your Payments instance password. It also updates the encrypted data in your 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_installdir/instances/payments_instance_name/xml directory.
The PaymentsInstance.properties file in the WC_installdir/payments/instances/payments_instance_name directory.
The server.xml file in the WC_profiledir/config/cells/cell_name/nodes/node_name/servers/payments_instance_name_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 your Payments database)
BankServACHOrder (if it exists in your Payments database)
VisaNetOrder (if it exists in your Payments database)
PaymentechOrder (if it exists in your Payments database)

About this task

The ChangePassword utility can change the value and location of your Payments instance password. It will also update the encrypted data in your Payments database. Ensure that you have followed the back up recommendations before going on to run the ChangePassword utility.

Procedure

If your 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:
1. Stop the Payments instance.
2. Stop Configuration Manager.
3. Using the command line, switch to the WC_installdir/payments/bin directory.
4. Run the ChangePassword utility as follows:
```
ChangePassword payments_instance_name
```
5. Enter the current password and the new password using the command line when prompted.
If your Payments instance password is currently stored in the Payments instance.xml file, and you want to move it to another location while changing its value, do the following steps:
1. Stop the Payments instance
2. Stop Configuration Manager.
3. If you are using the default keys configuration file WCKeys.xml in the WC_installdir/payments/xml/config directory, you need to 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 as follows:
```
<?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.
4. 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_installdir/instances/payments_instance_name/xml
```
  For example, this value might be KeysConfigFile="config/CustomKeys.xml"
5. Using the command line, switch to the WC_installdir/payments/bin directory.
6. Run the ChangePassword utility with "-k" flag:
  For example,
```
ChangePassword payments_instance_name -k
```
7. Edit the keys configuration file.
  Remove the "current" key provider and mark the "new" one as "current".
8. Start the Payments instance.
If your Payments instance password is currently stored in an external file, and you want to change the value of the Payments instance password, do the following steps:
1. Stop the Payments instance
2. Stop Configuration Manager.
3. Modify your 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 as follows:
```
<?xml version="1.0" encoding="UTF-8"?>
   <keys>
      <key value="123abc" />
   </keys>
```
4. 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_installdir/instances/payments_instance_name/xml
```
  For example, this value might be KeysConfigFile="config/CustomKeys.xml"
5. Using the command line, switch to the WC_installdir/payments/bin directory.
6. Run the ChangePassword utility with "-k" flag.
```
ChangePassword <payments_instance_name> -k
```
7. 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 as follows:
```
<?xml version="1.0" encoding="UTF-8"?>
  <keys>
    <key value="123abc" />
  </keys> 
```
8. Start the Payments instance.