Machine Key and Encryption in AbleCommerce Gold

Version: AbleCommerce Gold R10 SR1 and higher versions

Last Update: 11/27/17

Note:  The changes in this document will require access to the application server.

 

 

Important Information regarding Data Encryption

Summary of Data Encryption Process

Sensitive data, such as passwords, credit card information, and gateway connection credentials, can be stored in the AbleCommerce database.  This information is  encrypted using the Encryption Key that is manually set within the Ablecommerce Merchant Admin. This is called the Data Encryption Key (DEK). So, for each time you try to read/write any encrypted data, the DEK will be needed to perform that step - otherwise it will fail.

PA-DSS/PCI compliance requires that you protect your Data Encryption Key by encrypting its contents. This is a second layer of protection in case the server is compromised.  If someone gains access to your data encryption key (DEK), this second layer of encryption, called Key Encryption Key (KEK), will encrypt the actual contents of your encryption key file.

Missing gateway configuration issue

There is a known, but rare, issue with the gateway configuration data disappearing after the server is restarted or application pool recycled.  The issue doesn't affect everyone, and we have been unable to figure out what unique set of circumstances/configurations causes it to happen.

The problem is related to changes made in AbleCommerce Gold version R10 SR1.  This is where we implemented the second layer of encryption, the Key Encryption Key (KEK). AbleCommerce relies on the Windows managed machine key, and for some reason, on some computers, the system managed machine key changes upon application restart. This results in the inability to read the data encryption key (DEK), which was protected by the previous machine key prior to application restart.

The encrypted data and encryption key are still valid.  The application is simply not able to read the encrypted data.


Next Steps

If you are missing gateway configuration data, and you don't have your AbleCommerce encryption key backup, then you will need to complete Step 1), Step 2), Step 3b) and Step 4) below.  Prepare to re-enter your gateway configuration data.

If you do have your current encryption key backup, then complete Step 1), Step 2), Step 3a) and Step 4) below.

 

Step 1) Backups - DO NOT SKIP this step

In this step, find your backup AbleCommerce encryption key (if you have one), and backup the current web.config file.

  1. From the server, make a backup copy of the {wwwroot}\ web.config file in the application root folder.

  2. Locate your backup key.bin file and have it ready.
    If you do not have this backup, then locate all of your gateway connection credentials for payment, shipping, and tax, as needed.

    Note: This is the AbleCommerce encryption key backup file, which is created manually and should have been stored in a safe place.


Step 2) Create a machine key for the web.config

This next step will create the machine key and automatically update your web.config file.

  1. Open IIS Manager.

  2. Select the website for the AbleCommerce store and stop the application from running.

  3. Now, double-click the Machine Key icon in the ASP.NET section.

  4. Uncheck all checkboxes as shown:

  1. In the Action column, Click Generate Keys,

  2. Now click Apply to update the web.config file automatically.

  3. Restart the website.  Immediately proceed with one of the following steps.


Step 3a) Restore existing Encryption Key

Complete this step if you have your encryption key backup, otherwise, move on to Step 3b.

  1. Login to AbleCommerce Merchant Menu and go to the Configure > Security > Encryption Key page.

  2. Within the "Restore Encryption Key" section, use the Browse... button to select your key backup file (key.bin).

  3. Press the RESTORE KEY button.

  4. Restart the website.

  5. Go to any of the Configure Gateway pages and confirm the data in the connection fields exists.

Skip to Step 4.


Step 3b) Re-enter gateway connection information

Complete this step if you do not have a backup of your encryption key.

  1. For each gateway that is in use, you will need to re-enter the connection information.  You do not need to remove or reconfigure the settings, only enter the lost configuration settings.  To do this, reference the AbleCommerce Merchant Guide.  All gateways are documented under the Configure menu.

  2. Restart the website.

  3. Go to any of the Configure Gateway pages and confirm the data in the connection fields still exists.

 

Step 4) Setting a new Encryption Key

The last step describes the process of encrypting your data.  To be PA-DSS/PCI compliant, you should be encrypting your data at least once every 90 days.

  1. Login to AbleCommerce Merchant Menu and go to the Configure > Security > Encryption Key page.

  2. Type in some random text in the Random Text field.

  3. Click the Change Encryption Key button.  This will encrypt your data using the new machine key.

  4. Use the Get Backup button and save this key in a safe place.

 

Helpful Tips

  • Remember - If your server crashes, or you need to move the installation, these backups will allow you to retain and read the encrypted data in the database.

  • Storing backups:  Always keep backups and store them in a safe place - one that is not accessible to the internet.

  • Reference Merchant Guide for help creating and backing up Encryption Keys.

 
(Optional) Check the Load User Profile setting

The extra protection code (KEK) for the encryption key (DEK) requires the Load User Profile setting to be enabled for the Application Pool.  This will usually be the default setting.

  1. Open IIS Manager.

  2. Find the application pool for the AbleCommerce store.

  3. Open the Advanced Settings screen.

  1. Confirm the Load User Profile setting is True.