org.apache.derby.impl.services.jce

Class JCECipherFactory

java.lang.Object

org.apache.derby.impl.services.jce.JCECipherFactory

All Implemented Interfaces:

CipherFactory

public final class JCECipherFactory
extends java.lang.Object
implements CipherFactory

This CipherFactory creates new JCECipherProvider.

See Also:

CipherFactory

Field Summary

Fields inherited from interface org.apache.derby.iapi.services.crypto.CipherFactory

DECRYPT, ENCRYPT, MIN_BOOTPASS_LENGTH

Constructor Summary

Constructors

Constructor and Description
JCECipherFactory(boolean create, java.util.Properties props, boolean newAttributes)

Method Summary

Modifier and Type	Method and Description
java.lang.String	changeBootPassword(java.lang.String changeString, java.util.Properties properties, CipherProvider verify)
CipherProvider	createNewCipher(int mode) Returns a CipherProvider which is the encryption or decryption engine.
java.security.SecureRandom	getSecureRandom()
void	saveProperties(java.util.Properties properties)
void	verifyKey(boolean create, StorageFactory sf, java.util.Properties properties) The database can be encrypted with an encryption key given in connection url.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JCECipherFactory

public JCECipherFactory(boolean create,
                        java.util.Properties props,
                        boolean newAttributes)
                 throws StandardException

Throws:

StandardException

Method Detail

getSecureRandom

public java.security.SecureRandom getSecureRandom()

Specified by:

getSecureRandom in interface CipherFactory

createNewCipher

public CipherProvider createNewCipher(int mode)
                               throws StandardException

Description copied from interface: CipherFactory

Returns a CipherProvider which is the encryption or decryption engine.

Specified by:

createNewCipher in interface CipherFactory

Parameters:

mode - is either ENCRYPT or DECRYPT. The CipherProvider can only do encryption or decryption but not both.

Throws:

StandardException - Standard Derby Error Policy

saveProperties

public void saveProperties(java.util.Properties properties)

Specified by:

saveProperties in interface CipherFactory

changeBootPassword

public java.lang.String changeBootPassword(java.lang.String changeString,
                                           java.util.Properties properties,
                                           CipherProvider verify)
                                    throws StandardException

Specified by:

changeBootPassword in interface CipherFactory

Throws:

StandardException

verifyKey

public void verifyKey(boolean create,
                      StorageFactory sf,
                      java.util.Properties properties)
               throws StandardException

The database can be encrypted with an encryption key given in connection url. For security reasons, this key is not made persistent in the database. But it is necessary to verify the encryption key when booting the database if it is similar to the one used when creating the database This needs to happen before we access the data/logs to avoid the risk of corrupting the database because of a wrong encryption key. This method performs the steps necessary to verify the encryption key if an external encryption key is given. At database creation, 4k of random data is generated using SecureRandom and MD5 is used to compute the checksum for the random data thus generated. This 4k page of random data is then encrypted using the encryption key. The checksum of unencrypted data and encrypted data is made persistent in the database in file by name given by Attribute.CRYPTO_EXTERNAL_KEY_VERIFYFILE (verifyKey.dat). This file exists directly under the database root directory. When trying to boot an existing encrypted database, the given encryption key is used to decrypt the data in the verifyKey.dat and the checksum is calculated and compared against the original stored checksum. If these checksums dont match an exception is thrown. Please note, this process of verifying the key does not provide any added security but only is intended to allow to fail gracefully if a wrong encryption key is used StandardException is thrown if there are any problems during the process of verification of the encryption key or if there is any mismatch of the encryption key.

Specified by:

verifyKey in interface CipherFactory

Parameters:

create - true means database is being created, whereas false implies that the database has already been created

sf - storageFactory is used to access any stored data that might be needed for verification process of the encryption key

properties - properties at time of database connection as well as those in service.properties

Throws:

StandardException