• Overview
• Configuration
• Operation
• Backwards compatibility
• dbkeyutil utility
• dbutil script syntax
• dbkeyupdate command
• database catalog table
• Risks and pitfalls

Overview

Using database encryption does NOT protect against weak database passwords or incorrect database security settings (like user, group, member or dataset privileges). It is also NOT suitable to protect client connections across insecure networks, for example.

When using encryption, the database server maintains a list of one or more data encryption keys per database. Each dataset entry containing encrypted items uses one of those data encryption keys to protect the item contents. New or updated entries always use the most recently created data key. This allows "rolling data key changes" without the need for a database downtime to re-encrypt all data.

The data encryption keys are stored (in encrypted form) inside the database volume files, protected by so-called "master keys".

Master keys are created outside the database server and stored in special text files, protected by individual passphrases. The master key(s) must be submitted to the database server so that it can decrypt its internal data encryption keys and use those for accessing encrypted dataset fields.

The master key submission has to be performed after each start of the database server. Without the master keys, the database server is unable to read or write encrypted items.

Similar to the database server, tools like dbbexp or fwaudit, which access encrypted information directly also need to be provided the master keys before they are able to process encrypted dataset fields. On the other hand, utilities like dbrecover or dbrepl do not need to know the master keys, as their processing does not involve "unpacking" of encrypted item content.

Master keys may optionally be created as multi-part keys. With multi-part keys, all parts have to be submitted to the database server to be active. Using multi-part keys allows authorization schemes where keys are spread across independent key owners and all the involved parties are required for successful key submission.

Configuration

Please note that after configuring one or more dataset fields for encryption, the database server always needs the associated master key(s) before being able to read or write encrypted data items. It is therefore crucial that you carefully keep the key files and their passphrases. Loss of the keys or their passphrases will result in the irrecoverable loss of the associated encrypted database (and forward log) contents.

Step 1: generate master key with dbkeyutil

Here is an example:

$ dbkeyutil keygen mykey
Enter passphrase for mykey:
Confirm passphrase:

Note: Please make a copy of the key file and document the passphrase. Place this in a secure location. Loss of either the key file or the passphrase will result in losing access to encrypted data.

Step 2: submit master key to the database server with dbkeyutil

Here is an example:

$ dbkeyutil -u dba submit mykey
Enter passphrase for mykey:
Passphrase is valid
Master key submitted successfully

The dbkeyutil status command may be used to review the list of active master keys on the database server, as shown in the example below:

$ dbkeyutil status
idx  master key checksum              stat type     ts
---- -------------------------------- ---- -------- -------------------
1    9f452bd41b7d669d1e2da1a4fdea8522 ACTV AES 128  2009-11-25 15:23:50

Step 3: use dbutil to create data encryption keys

Use dbutil to trigger the creation of data encryption keys. These keys are stored inside the database volume files, protected by a master key. You reference the desired master key in your dbutil command by specifying its checksum (available from your keyring file or dbkeyutil status output).

Here is an example:

$ dbutil -v -

ELOQUENCE DBUTIL (C) Copyright 2010 Marxmeier Software AG (B.08.10)
Processing script ...

database "mydb";
create encryption key using "9f452bd41b7d669d1e2da1a4fdea8522";
exit;
done

Note that Step 3 and Step 4 may be combined in a single dbutil session.

Step 4: use dbutil to configure dataset fields as encrypted

Use dbutil to apply the changes. It will restructure the associated sets.

Here is an example:

$ dbutil -v -

ELOQUENCE DBUTIL (C) Copyright 2010 Marxmeier Software AG (B.08.10)
Processing script ...

database "mydb";
change set "invoices" set encrypted;
change item "order-date" in "orders" set encrypted;
change item "price" set encrypted;
exit;
Checking database consistency ...
Consistency check completed successfully

Database restructure analysis:
 PRODUCTS
  * Record reorganized due encryption change
 INVOICES
  * Record reorganized due encryption change
 ORDERS
  * Record reorganized due encryption change
Data restructure process required.

Uploading modified schema ...
Restructuring database ...
done

Note that Step 3 and Step 4 may be combined in a single dbutil session.

Please note that after configuring encrypted items, the database server must be provided with the valid master key after every server restart. Otherwise it will not be able to access the contents of encrypted items.

To remove item encryption, you may use the above dbutil commands with an "unset encrypted" clause. However, this also will only be possible if the server has been provided with valid master key via dbkeyutil submit.

Operation

When using databases with encrypted items in conjunction with replication, you also need to submit the respective master keys to the slave server(s) if or when access to the slave server databases is desired. The data replication itself also works without master keys being present in the slave server(s).

Database auditing is also affected by the use of encrypted items. Access to encrypted data is only possible when supplying the relevant master keys in the fwaudit invocation. If the contents of encrypted items are not of interest, fwaudit may also be used without specifying any master keys; it will then return blank or zero values for the inaccessible encrypted items.

Please note that the fwutil library does not currently support the use of master keys. Consequently, encrypted information is not available.

Note that you may need "historic" master keys when attempting to perform database auditing using older forward logs or when trying to access databases restored from older backups. It is thus advisable to carefully document and archive the "history" of master keys, especially when changing master keys in periodic intervals for security reasons.

To change the passphrases of master keys (periodically), you may use the dbkeyutil chpass command. Note that archived copies of the keyfile will still need the previous passphrases to be used.

To change master keys for specific databases (periodically), you may use the "change all encryption keys using ..." command in dbutil. Note that older database backups and forward logs will still need the previous master keys to be used.

To change the data encryption keys for specific databases (periodically), you may use the "create encryption key" command in dbutil. Note that this only affects the encryption of database entries added or updated subsequently. To also re-encrypt older entries and retire older data encryption keys from the database, you may use the dbctl dbkeyupdate command (which may run for a while, consuming CPU and disk I/O resources).

Note that changing or retiring data encryption keys is independent of any changes to the associated master keys or their passphrases.

Backwards compatibility

Encrypted databases are not compatible to previous Eloquence versions. Attempting to access data or an index that holds encrypted data with a previous Eloquence version is likely to result in a server abort or corrupted data. When encrypting data, the record size and layout differs and previous Eloquence versions are currently not able to detect this.

Databases are fully compatible to with previous versions when no encryption is used.

dbkeyutil utility

Find more information in the dbkeyutil document.

dbutil script syntax

DATABASE "example";

UPGRADE DATABASE;

The following command is used to create a data encryption key:

CREATE ENCRYPTION KEY [ ("type") ] 
USING [MASTER KEY] "master key";

Supported encryption types are:

• AES - AES 128 bit
• AES128 - AES 128 bit
• AES256 - AES 256 bit

For example:

CREATE ENCRYPTION KEY("AES256")
USING MASTER KEY "330d6de453136a93fd99c1638fd645fd";

The following command may be used to remove data encryption keys if the database does not use encrypted information. It fails if encryption is used in the database.

DELETE ALL ENCRYPTION KEYS;

Data encryption keys may be changed to use a new master key. This may be used to replace a master key. To succeed, both the previous and the new master keys need to be present in the server.

The following command may be used to assign all data encryption keys of a database to the designated master key:

CHANGE ALL ENCRYPTION KEYS USING [MASTER KEY] "master key";

The commands below may be used to designate a field as encrypted or unencrypted:

CHANGE ITEM item-name [IN set-name] SET ENCRYPTED;
CHANGE ITEM item-name [IN set-name] UNSET ENCRYPTED;

Please note: encryption status is maintained for each field (item in a data set). When adding a field to a data set, it defaults to unencrypted.

The following commands may be used to designate all fields in a data set as encrypted or unencrypted:

CHANGE SET set-name SET ENCRYPTED;
CHANGE SET set-name UNSET ENCRYPTED;

The SET or UNSET ENCRYPTED may also be used in a change set context (enclosed in brackets).

For example:

CHANGE SET customers {
  UNSET ENCRYPTED;
  CHANGE ITEM turnover SET ENCRYPTED;
}

dbkeyupdate command

Find more information in the dbkeyupdate document.

database catalog table

For example:

$ dbdumpcat -t 13 mydb

---------------------------------------------------------------------------------
#13 syskey (1 entries)
---------------------------------------------------------------------------------
|kid |tableid|type|tskey     |key             |kcheck          |mcheck          |
---------------------------------------------------------------------------------
|1   |0      |2   |2009-11-25|16:4b50922ca12f |16:e6da66d666f1 |16:9f452bd41b7d |
---------------------------------------------------------------------------------

Use the dbdumpcat -n option to show the "mcheck" column in full length.

They "key" and "kcheck" columns contain the data encryption key and a checksum. The data encryption key is, of course, stored encrypted with its associated master key.

Risks and pitfalls

Loss of keys or passphrases

Please keep in mind that the master key and its pass phrase is required as long as backups need to be accessible.

Encryption overhead

Enabling encryption requires additional CPU resources, depending on the amount of encrypted items and the frequency records holding encrypted data are accessed. In our testing we encountered about 20% additional CPU resources required in a benchmark when encrypting the entire database.