EnableDatabaseEncryption

The EnableDatabaseEncryption action enables database encryption. The syntax of the EnableDatabaseEncryption action is as follows.

jdbcrypt path=database-path
         ini=initialization-file-name
         action=EnableDatabaseEncryption
                ExportPath=file-path
                [AccessCheck=Default|Strong|None]
                [MultipleExport=true]
                [MandatoryFullEncryption=true|false]

You can specify the optional argument MultipleExport with a value of true, but this allows anyone who knows the master key passphrase to export additional copies of the master key for abuse elsewhere. This is not recommended.

The following is an example of the EnableDatabaseEncryption action.

jdbcrypt path=d:\dbcrypt ini=d:\salesdb\jade.ini action=EnableDatabaseEncryption ExportPath=d:\temp

Enabling database encryption generates the encryption Universal Unique Identifier (UUID), encryption timestamp, and the master key, and then updates the database control file with these details, to mark the database as encryption-enabled. It also exports the encrypted master key to a text file for separate secure storage.

You are prompted twice to enter the master key passphrase, which must be a minimum of 15 characters containing at least four letters, four digits, and two other characters; for example, abcdefg+=123456.

The title of the database master key is generated from the database encryption UUID and timestamp; for example:

Jade Software Corporation Limited.JADEDB.Master.b422f147-879d-01cb-1027-00001d93f502.20101119035612199

By default, the master key is marked so that it can be exported once only from the keystore at the time it is created. A less‑secure option is to specify the MultipleExport argument with a value of true, in which case the master key can also be exported at a later date.

The value of the ExportPath argument is the name of the directory to which the file containing the exported key is written. The name of the file is defined by the database encryption UUID and timestamp; for example:

JADEDB.Master.25146be6-8aca-01cb-1027-0000e329f802.20101123045153031.txt

The content of the file is plain ASCII text that can be printed as a backup to a copy of the file stored on removable media such as a pen drive (USB flash drive). You can make multiple copies of the exported key file. The file can be reconstructed by typing the printed contents into a text editor and saving it with the file name specified in the first line of text.

You must manually enter an export file passphrase, which is used to encrypt the master key before it is written. The export file passphrase, which should be different from the master key passphrase, has the same strength requirements.

Store the exported key file in a secured location and a sealed printed copy of the export file passphrase in another secure location.

If you lose the exported master key or its export file passphrase, you cannot move the database to another machine or restore the contents of the keystore if it is lost or corrupted. In this case, you will be unable to access or decrypt the contents of the database.

When a new database map file is added to a fully encrypted database, the new file will be unencrypted, which will result in your database being partially encrypted if you forget to specifically encrypt the new file.

Mandatory full encryption does not cause files to be automatically encrypted. No files are automatically encrypted.

If you want mandatory encryption of all files in your database, specify the MandatoryFullEncryption=true argument (the default value is false). When this argument is set to true, the database server rejects attempts to create user objects in unencrypted user data map files. However, objects can be read, updated, and deleted.

New map files added to a database are always added as unencrypted, regardless of the setting of the optional MandatoryFullEncryption argument. Should these files require encryption or the MandatoryFullEncryption argument is set to true, the files must be manually encrypted using the JADE Database Encryption utility (jdbcrypt.exe).

When MandatoryFullEncryption is set to true, it requires that all map files are encrypted before any attempt is made to create new objects in any map file, or exception 3345 (DbCrypt Cannot create user objects in unencrypted files) is raised.

Situations in which a database may be partially encrypted and where MandatoryFullEncryption should be set to false are as follows.

Only certain map files contain data sensitive enough to require encryption
Map files that can be created by the user logic are unencrypted and as such, would be unable to create objects

If you want to verify the encrypted status of all files in your database, run the ListStatus action regularly.

For details about the optional AccessCheck argument, see "Access Check Options", earlier in this chapter.