Transparent Table/Column Encryption ​

What is it? ​

Hazaar DBI has the ability to encrypt data automatically on it's way through to the database. Once enabled, this encryption is performed in the DBI layer without ANY changes to code for insert, update or select. This not only adds an extra layer of security over the wire, but allows selected data to be stored securely in a database so that only the application can decrypt it.

Encryption can be activated on a whole table, or on individually selected columns in a table. In each case, only string values are supported (why would you want to encrypt and number or boolean???), and due to the encryption producing varying length data, these columns should be created as TEXT type columns to ensure there is enough column storage to hold the encrypted values.

Enabling Encryption ​

Encryption requires a unique encryption key that is used to encrypt and decrypt data. This key can be pretty much anything you want but a decent-sized string of randomly generated characters is recommended.

Once you have your key ready to go you can update your database configuration to enable encryption. Let's quickly see what that looks like first.

{
    "development": {
        ... _ other config options ...
        "encrypt": {
            "key": "{your encryption key}" <--Optional and only recommended for testing
            "table": {
                "users": [ "password" ],
                "credit_data": true
            }
        }
    }
}

In the above example we enable encryption on two tables. In the users table, a single column named password will be encrypted. In the credit_data table, all string columns will be encrypted.

Keeping Your Key Safe ​

While specifying the key in the configuration is a quick and easy way to get up and running with encryption, it certainly is not recommended for production systems. For these systems, security is priority so we have the ability to store our key in the config directory in a file name .db_key (by default).

So using your favourite text editor, simply open the key file and pop in your key. On Linux you can do something like this:

> echo "{your encryption key}" > {APPLICATION_PATH}/application/configs/.db_key

Where your encryption key is (obviously) YOUR ENCRYPTION KEY and APPLICATION_PATH is your root application path that contains the application and public directories.

Configuration Options ​

Below is the full list of available configuration options in the encrypt config object of the database config.

cipher (default: aes-256-ctr) ​

The encryption algorithm to use to encrypt/decrypt data. This can be ANY algorithm supported by the OpenSSL in PHP. You can use the openssl_get_cipher_methods() function to get a list of available algorithms on your system. See the PHP documentation for openssl-get-cipher-methods for more information.

table ​

The table object is a key/value object where the key is the name of the table to encrypt and the value is either a boolean to enable/disable whole table encryption, or is an Array of column names that should be encrypted.

Encrypt a whole table ​

{
    "tablename": true
}

Encrypt selected columns in a table ​

{
    "tablename": [ "column1", "column2", "column3" ]
}

checkstring (default: !!) ​

The check string is used to detect if the decryption has been successful. It is just 1 or 2 character that are prefixed to value before encryption, and checked that they exist after decryption to indicate success before being stripped off again. This can be anything but 2 characters is recommended to keep it short but allow good detection reliability in case a single character magically decrypts to the correct character. Normally the default is fine.

key ​

It's not recommended that this is used in a production environment. Specify your encryption key here to get up and running quickly.

keyfile (default: .db_key) ​

The keyfile option can be used to specify the path to an alternative key file. This can be either a relative path to the configs directory, or an absolute path which allows you to keep the file in an even more secure location outside of the application path.