Change Payments instance password and updating encrypted data using ChangePassword

  1. It is strongly recommended to back up the following files before running the ChangePassword utility:

    1. The Payments instance.xml file in the WC_installdir/instances/payments_instance/xml directory.

    2. The PaymentsInstance.properties file in the WC_installdir/payments/instances/payments_instance directory.

    3. The server.xml file in the WAS_installdir/profiles/profile/config/cells/cell/nodes/node/servers/payments_instance_Commerce_Payments_Server directory.

  2. It is strongly recommended to back up the following tables in the Payments database before running the ChangePassword utility with the "-k" flag:

    1. ETKey

    2. ETBinaryData

    3. OfflineCardOrder (if it exists in your Payments database)

    4. BankServACHOrder (if it exists in your Payments database)

    5. VisaNetOrder (if it exists in your Payments database)

    6. PaymentechOrder (if it exists in your Payments database)

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 above before going on to run the ChangePassword utility

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

    1. Stop the Payments instance.

    2. Stop WebSphere Commerce Configuration Manager.

    3. Run the ChangePassword utility as follows:
      ChangePassword <payments_instance>

    4. You will be prompted for the current password and new password in command line.

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

    1. Stop the Payments instance.

    2. Stop WebSphere Commerce Configuration Manager.

    3. If you are using the default keys configuration file WCKeys.xml in the WC_installdir/payments/xml/config directory (which is the default behavior when installing the fix pack with PCI feature delivered), 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 an attribute KeysConfigFile 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 instance.xml directory:
      WC_installdir/instances/payments_instance/xml

    5. Run the ChangePassword utility with "-k" flag: For example, KeysConfigFile="config/CustomKeys.xml". ChangePassword <payments_instance> -k

    6. Edit the keys configuration file: remove the "current" key provider and mark the "new" one as "current".

    7. Start the Payments instance.

  3. If your Payments instance password is currently stored in an external file, and you want to change the value of the Payments instance password...

    1. Stop the Payments instance.

    2. Stop WebSphere Commerce 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 an attribute KeysConfigFile in the PMInstance section of the Payments instance.xmlfile. The attribute points to the custom keys configuration file with a relative path to the Payments instance.xml directory:
      WC_installdir/instances/payments_instance/xml
      For example, KeysConfigFile="config/CustomKeys.xml".

    5. Run the ChangePassword utility with "-k" flag: ChangePassword <payments_instance> -k

    6. 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:

    7. Start the Payments instance.

Related concepts

Related tasks

Related references