X-Cart:Blowfish

Data encryption methods used in X-Cart

Security of sensitive data in your store's database is ensured by Blowfish encryption algorithm. Two methods of data encryption using this algorithm are available:

• Blowfish key based encryption method
• Merchant key based encryption method

Blowfish key based encryption method

Blowfish key based encryption method is used to encrypt the following types of data in the database:

1. user passwords;
2. sensitive data (like cardholders' data) which is stored in the details field of the xcart_orders table (i.e. data displayed in the 'Order details (not visible to customer and provider)' field on the Order Details page);
3. some internal data (merchant account passwords, keys, etc).

Blowfish key based encryption method is enabled by default; it cannot be disabled. With this method, the above said types of data in the database are encrypted using the so-called Blowfish key - a special key stored in your X-Cart's main configuraton file config.php (see the $blowfish_key variable). Without this key, the encrypted data cannot be decrypted and read, which means your data will remain protected even if a hacker gains access to the database (that, of course, provided your store's config.php has not been compromised as well). Initially, the Blowfish key is generated for your store during X-Cart installation. It can be changed at a later time using the built-in utility for Blowfish key re-generation (You don't have to do it, but periodically changing your store's Blowfish key is a good thing). Note that using the Blowfish key based encryption method does not affect your work in the store's back end in any way: you do not need to enter any security key to view the encrypted order data; you just log in to the Admin back end, and the order data is automatically decrypted and displayed in the "Order details..." section.

Changing your Blowfish key

It is quite safe to use the Blowfish key generated during X-Cart installation for some time; however, it is recommended that you periodically change your store's Blowfish key - for the same reasons that you should change from time to time the passwords you use for accessing your store's Admin area, FTP, SSH, etc.

To change the Blowfish key, use the utility for re-generation of the Blowfish encryption key provided with X-Cart tools (For details, see the section X-Cart's Advanced Tools in the 'Maintaining Your Store' section of this manual).

Important: Never try to change your Blowfish key by editing the value of the $blowfish_key variable in config.php: your data is already encrypted with this key and X-Cart needs exactly the same key to be able to decrypt it. Editing $blowfish_key manually will corrupt all the user passwords, including the administrator password, so you will not be able to use the store.

Please be aware that a lost Blowfish key cannot be restored, so X-Cart team will not be able to help you regain access to your store if you remove or manually change the value of $blowfish_key.

Merchant key based encryption method

Merchant key based encryption method is used only for data stored in the details field of the xcart_orders table, i.e. data displayed in the 'Order details (not visible to customer and provider)' section on the 'Order Details' page.

Unlike Blowfish key based encryption, Merchant key based encryption is an additional (optional) feature. You can enable it to ensure a still higher level of security for your customers' data, but you do not have to use it if you do not want to.

When you enable this method, you create a Merchant key - a special secure key that is used by X-Cart to encrypt the details of your customers' orders and to decrypt previously encrypted order details when you wish to view them. Once a Merchant key is defined/entered in X-Cart admin back-end, the data stored in the details field of the xcart_orders table is automatically re-encrypted using the Merchant key specified.

The higher level of security provided by this method is ensured by the fact that the key used to encrypt and decrypt order details is not stored anywhere in the system. The only thing that is stored is an MD5 signature of the key.

When you need to view any order details that were encrypted using your store's Merchant key, you must log in to the admin back end of your store and enter your current Merchant key into a special form on the 'Order details' page. The system will calculate the MD5 hash of the Merchant key entered and compare it to the MD5 signature of the original Merchant key stored in your store's database. If the signatures are deemed to be identical, you will be allowed to view the order details.

After you enter your store's Merchant key into the system, it remains valid until the user session expiration (by default, the duration of user session in X-Cart is set to one hour) or until the user logs out. This means you need to enter your store's Merchant key only once per user session (no need to enter it every time you need to view encrypted order data). When the user session is ended/expired, you will need to re-enter the current Merchant key in order to view the encrypted order data.

To be able to change your store's Merchant key or to disable Merchant key based encryption altogether, you will be required to enter your current Merchant Key.

As Merchant key is not stored anywhere in the system, it is essential that you keep it in a safe place. If you forget your current Merchant key, you will not be able to restore it, which means you will not be able to decrypt and view the order data encrypted using this key.

Enabling Merchant key based encryption

To enable Merchant key based encryption method in your store, do the following:

1. In the 'General Settings/Security options' section of your store's Admin area, enable the option 'Enable merchant key based blowfish encryption method'. A page titled 'Add merchant key' opens. This page provides a form for creating a Merchant key:
   
2. Think of a password that you would like to use for access to order details in your store and enter it into the 'Merchant key' field of the 'Add merchant key' form. Make sure this password is at least 6 characters long.
3. Enter the password once again into the 'Confirm merchant key' field.
4. Click the Submit Query button.

After you click on Submit Query, Merchant key-based Blowfish encryption is enabled in your store. Any data which has been encrypted by this time using the hard-coded Blowfish key from config.php is decrypted and re-encrypted using the Merchant key you provided. On completion, a message is displayed confirming that the order details have been successfully re-encrypted with the Merchant key.

Using your Merchant key to access order details and to apply encryption to new orders

After the creation of a Merchant key, a form titled 'Enter merchant key' will appear on the 'Order details' page.

You will see this form in any new user session when you attempt to view your customers' orders. To access the details of any order in the database, you will need to enter your Merchant key into the appropriate field in this form and click the Enter button. The form will disappear as soon as you enter a valid Merchant key and will not be displayed again until the session expires.

Please be aware that, because your Merchant key is not stored in the system, new orders getting placed by your customers will not be encrypted with the Merchant key right away. After placement, they will be encrypted with the Blowfish encryption key stored in the variable $blowfish_key in config.php. To get new orders encrypted using your Merchant key, you must enter your Merchant key into the system. After that, any new orders that have been created by this time and encrypted using the Blowfish key will be decrypted and re-encrypted using the Merchant key.

Using the 'Enter merchant key' form in the Admin area is not the only way of providing your Merchant key to the system. You can initiate re-encrypting of order details remotely by entering the following line into the address bar of your web browser:

http://www.example.com/xcart/admin/post_recrypt.php?merchant_password=12345

replacing http://www.example.com/xcart/ with the actual address of your store and 12345 with your actual Merchant key.

Alternatively, you can use the command line:

/usr/bin/php {xcart_root_dir}/admin/post_recrypt.php merchant_password=12345

({xcart_root_dir} must be replaced by your X-Cart root directory and 12345 with your Merchant key).

Changing your Merchant key

It is possible to change a previously created Merchant key.

To change your merchant key:

1. Select Tools->Change merchant key.
   
2. Enter your store's current Merchant key and the new key, then type in the new key once again for confirmation.
3. Click Submit. Provided you have entered valid information in all the fields, the Merchant key will be updated.

Disabling Merchant key based encryption

Merchant key-based Blowfish encryption cannot be disabled without first entering a valid current Merchant key. This guarantees that encryption of order details will not be disabled by a person who is not authorized to do so even if this person gains access to the Admin area.

To disable Merchant key based encryption:

1. Go to the 'General Settings/Security options' section of the Admin area.
   If you have already entered your Merchant key in the current session, the option 'Enable merchant key based blowfish encryption method' will look as follows:
   
   This means you can proceed to step 2.
   If you have not yet entered your Merchant key in the current session, the option 'Enable merchant key based blowfish encryption method' will look as follows:
   
   This means the option cannot be disabled until you have entered the current Merchant key into the system. Go to the 'Orders Management' section (Administration menu->Search for orders) and open the details of any order. The form 'Enter merchant key' will appear on the page. Enter your Merchant key into the appropriate field in this form and click Enter. Wait for the key to be applied and return to the 'General Settings/Security options' section. This time you should see a selected check box opposite the option 'Enable merchant key based blowfish encryption method'. Proceed to step 2.
2. Unselect the 'Enable merchant key based blowfish encryption method' check box.
3. Click the Save button. Merchant key based encryption will be disabled. The data that used to be encrypted using the Merchant key will be decrypted and re-encrypted using the Blowfish key stored in config.php.