Supporting Encryption

Berkeley DB optionally supports encryption using the Rijndael/AES (also known as the Advanced Encryption Standard and Federal Information Processing Standard (FIPS) 197) algorithm for encryption or decryption.

The algorithm is configured to use a 128-bit key. Berkeley DB uses a 16-byte initialization vector generated using the Mersenne Twister. All encrypted information is additionally checksummed using the Secure Hash Algorithm, which produces a 160-bit message digest.

The encryption support provided with Berkeley DB is intended to protect applications from an attacker obtaining physical access to the media on which a Berkeley DB database is stored. It also protects applications from attackers who compromise a system on which Berkeley DB is running but who are unable to read system or process memory on that system. However, the encryption support provided with Berkeley DB will not protect applications from attackers who are able to read system memory on the system where Berkeley DB is running.

To encrypt a database, you must configure the database for encryption prior to creating it. If you are using a database environment, you must also configure the environment for encryption.

  • Follow the steps below to create an encrypted database within an environment:

    1. Configure the environment for encryption using the DB_ENV->set_encrypt() method.

    2. Open the database environment.

    3. Specify the DB_ENCRYPT flag to the database handle.

    4. Open the database.

  • Follow the steps below for databases not created in an environment:

    1. Specify the DB_ENCRYPT flag to the database handle.

    2. Call the DB->set_encrypt() method.

    3. Open the database.

      Once you complete the configuration steps, all of the databases that you create in the environment are encrypted/decrypted by the password you specify using the DB_ENV->set_encrypt() method.


The only way to encrypt an unencrypted database is to dump the contents with the utility db_dump and re-create it in an encrypted form with db_load. Also, encrypted databases cannot be read on systems with a different endianness than the system that created the encrypted database.

When a database is encrypted, its log files are also encrypted, so accessing the logs also requires the encryption key. By default, logs are placed in the same directory as the environment. When using the SQL API, the logs are placed in the journal directory. Log files should never be simply deleted. For instructions on how to properly remove log files, see "Log File Removal" in the Oracle Berkeley DB Programmer's Reference Guide.

Each encrypted database environment (including all its encrypted databases) is encrypted using a single password and a single algorithm. For applications to have finer granularity of database access they must either use multiple database environments or implement additional access controls outside of Berkeley DB.

The only encrypted parts of a database environment are its databases and its log files. Specifically, the shared memory regions supporting the database environment are not encrypted (see, "Shared Memory Regions", in the Oracle Berkeley DB Programmer's Reference Guide for more information). For this reason, it may be possible for an attacker to read some or all of an encrypted database by reading the on-disk files that back these shared memory regions.

There are two ways to prevent such attacks. One is for applications to use in-memory filesystem support (on systems that support it). Another is to use DB_PRIVATE or DB_SYSTEM_MEM flags in the DB_ENV->open() method. These flags ensure that the shared memory regions are placed in memory that is never written to a disk. As some systems back up system memory to a disk, it is important to consider the specific operating system running on the machine as well.

Finally, when backing up database environment shared regions with the filesystem, Berkeley DB can be configured to overwrite the shared regions before removing them by specifying the DB_OVERWRITE flag. This option is effective only in the presence of fixed-block filesystems. Journaling or logging filesystems will require operating system support and probably modification of the Berkeley DB sources.

Whereas all user data is encrypted, parts of the databases and log files in an encrypted environment are maintained in an unencrypted state. Specifically, log record headers are not encrypted, only the actual log records are. Additionally, database internal page header fields are not encrypted. These page header fields include information such as the page's DB_LSN number and position in the database's sort order.

Log records and database pages distributed by a replication master to replicated clients are transmitted to the clients in unencrypted form. If encryption is desired in a replicated application, the use of a secure transport is strongly suggested and all sites in the replication group must use encryption.

Berkeley DB supports encryption using Intel's Performance Primitive (IPP) on Linux. This works only on Intel processors. To use Berkeley DB with IPP encryption, you must have IPP installed along with a cryptography extension. The IPP performance is higher in most cases compared to the current AES implementation. See "--with-cryptography" in the Oracle Berkeley DB Installation and Build Guide for more information. And for more information on "IPP", see Intel Integrated Performance Primitives – Documentation.