Working with Encryption

• Encrypting Databases on Creation
• Booting an Encrypted Database
• Changing the Boot Password

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.

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)

Note:

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:

jdbc:derby:encryptionDB1;create=true;dataEncryption=true;
    bootPassword=clo760uds2caPe

Note:

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.)

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
jdbc:derby:encryptedDB3;create=true;dataEncryption=true;
bootPassword=clo760uds2caPe;
encryptionProvider=org.bouncycastle.jce.provider.BouncyCastleProvider;
encryptionAlgorithm=DES/CBC/NoPadding
 
-- using a provider
-- available from
-- http://jcewww.iaik.tu-graz.ac.at/download.html
jdbc:derby:encryptedDB3;create=true;dataEncryption=true;
bootPassword=clo760uds2caPe;
encryptionProvider=iaik.security.provider.IAIK;encryptionAlgorithm=
DES/CBC/NoPadding

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:

algorithmName/feedbackMode/padding

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.

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:

jdbc:derby:wombat;bootPassword=clo760uds2caPe

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

Note:

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).

You can change the boot password for the current database.

CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY(
    '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.

Note:

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