apache > db
Apache DB Project
Font size:      

Working with Encryption

Working with Encryption

Encrypting Databases on Creation

Derby allows you to configure a database for encryption when you create it. To do so, you specify dataEncryption=true on the connection URL.

The Java Runtime Environment (JRE) determines the default encryption provider, as follows:

  • For J2SE/J2EE 1.4 or higher, the JRE's provider is the default.
  • For an IBM Corp J2SE/J2EE 1.3 JRE, the default provider is com.ibm.crypto.provider.
  • For a Sun Microsystem J2SE/J2EE 1.3 JRE, the default provider is com.sun.crypto.provider.SunJCE.
  • For any other J2SE/J2EE 1.3 JRE, a provider must be specified.

You have the option of specifying an alternate encryption provider; see Specifying an Alternate Encryption Provider. The default encryption algorithm is DES, but you have the option of specifying an alternate algorithm; see Specifying an Alternate Encryption Algorithm.

Creating the Boot Password

When you encrypt a database you must also specify a boot password, which is an alpha-numeric string used to generate the encryption key. The length of the encryption key depends on the algorithm used:

  • DES (the default) (56 bits)
  • DESede (168 bits)
  • all other algorithms (128 bits)
The boot password should have at least as many characters as number of bytes in the encryption key (56 bits=8 bytes, 168 bits=24 bytes, 128 bits=16 bytes). The minimum number of characters for the boot password allowed by Derby is eight.

It is a good idea not to use words that would be easily guessed, such as a login name or simple words or numbers. A bootPassword, like any password, should be a mix of numbers and upper- and lowercase letters.

You turn on and configure encryption and specify the corresponding boot password on the connection URL for a database when you create it:

If you lose the bootPassword and the database is not currently booted, you will not be able to connect to the database anymore. (If you know the current bootPassword, you can change it. See Changing the Boot Password.)

Specifying an Alternate Encryption Provider

You can specify an alternate provider when you create the database with the encryptionProvider=providerName attribute.

You must specify the full package and class name of the provider, and you must also add the libraries to the application's class path.

-- using the the provider library jce_jdk13-10b4.zip|
-- available from www.bouncycastle.org
-- using a provider
-- available from
-- http://jcewww.iaik.tu-graz.ac.at/download.html

Specifying an Alternate Encryption Algorithm

Derby supports the following encryption algorithms:

  • DES (the default)
  • DESede (also known as triple DES)
  • Any encryption algorithm that fulfills the following requirements:
    • it is symmetric
    • it is a block cipher, with a block size of 8 bytes
    • it uses the NoPadding padding scheme
    • its secret key can be represented as an arbitrary byte array
    • it requires exactly one initialization parameter, an initialization vector of type javax.crypto.spec.IvParameterSpec
    • it can use javax.crypto.spec.SecretKeySpec to represent its key

    For example, the algorithm Blowfish implemented in the Sun JCE package fulfills these requirements.

By Java convention, an encryption algorithm is specified like this:


The only feedback modes allowed are:

  • CBC
  • CFB
  • ECB
  • OCB

By default, Derby uses the DES algorithm of DES/CBC/NoPadding.

Specify an alternate encryption algorithm when you create a database with the encryptionAlgorithm=algorithm attribute. If the algorithm you specify is not supported by the provider you have specified, Derby throws an exception.

Booting an Encrypted Database

Once you have created an encrypted database, you must supply the boot password to reboot it. Encrypted databases cannot be booted automatically along with all other system databases on system startup (see "derby.system.bootAll" in Tuning Derby). Instead, you boot encrypted databases when you first connect to them.

For example, to access an encrypted database called wombat, created with the boot password clo760uds2caPe, you would use the following connection URL:


Once the database is booted, all connections can access the database without the boot password. Only a connection that boots the database requires the key.

For example, the following connections would boot the database and thus require the boot password:

  • the first connection to the database in the JVM session
  • the first connection to the database after the database has been explicitly shut down
  • the first connection to the database after the system has been shut down and then rebooted
The boot password is not meant to prevent unauthorized connections to the database once it has been booted. To protect a database once it has been booted, turn on user authentication (see Working with User Authentication).

Changing the Boot Password

You can change the boot password for the current database.

    'bootPasword', 'oldbpw , newbpw');

where oldbpw is the current boot password and newbpw is the new boot password. This call commits immediately; it is not transactional.

PropertyInfo.getDatabaseProperty("bootPassword"), or VALUES SYSCS_UTIL.SYSCS_GET_DATABASE_PROPERTY('bootPassword'), will not return the boot password.

Previous Page
Next Page
Table of Contents