Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.services.jce.JCECipherFactory

Modifier and Type	Class and Description
private static class	JCECipherFactory.EncryptedKeyResult

Modifier and Type	Field and Description
private static final String	AES
private static final int	AES_IV_LENGTH AES encryption takes in an default Initialization vector length (IV) length of 16 bytes This is needed to generate an IV to use for encryption and decryption process
private static final int	BLOCK_LENGTH
private String	cryptoAlgorithm
private String	cryptoAlgorithmShort
private String	cryptoProvider
private String	cryptoProviderShort
private static final String	DEFAULT_ALGORITHM
private static final String	DES
private static final String	DESede
private int	encodedKeyLength
private int	keyLengthBits
private byte[]	mainIV
private SecretKey	mainSecretKey
private static final String	MESSAGE_DIGEST
private MessageDigest	messageDigest
private Properties	persistentProperties
private static final String	TripleDES
private static final int	VERIFYKEY_DATALEN Amount of data that is used for verification of external encryption key This does not include the MD5 checksum bytes

Access	Constructor and Description
pack-priv	JCECipherFactory(boolean create, Properties props, boolean newAttributes)

Method Summary

Modifier and Type	Method and Description
public String	changeBootPassword(String changeString, Properties properties, CipherProvider verify) Implements org.apache.derby.iapi.services.crypto.CipherFactory.changeBootPassword.
public CipherProvider	createNewCipher(int is either ENCRYPT or DECRYPT. The CipherProvider can only do encryption or decryption but not both. mode) Implements org.apache.derby.iapi.services.crypto.CipherFactory.createNewCipher. Returns a CipherProvider which is the encryption or decryption engine.
private CipherProvider	createNewCipher(int mode, SecretKey secretKey, byte[] iv)
private byte[]	Returns: decrypted key decryptKey(String encryptedKey, int encodedKeyCharLength, byte[] bootPassword) Decrypt the secretKey with the user key .
private int	digest(byte[] input)
private JCECipherFactory.EncryptedKeyResult	Returns: hexadecimal string of the encrypted secretKey encryptKey(byte[] secretKey, byte[] bootPassword) Encrypt the secretKey with the boot password.
private byte[]	generateIV(byte[] secretKey) Generate an IV using the input secretKey that can be used by JCECipherProvider to encrypt or decrypt.
private SecretKey	generateKey(byte[] secretKey) Generate a Key object using the input secretKey that can be used by JCECipherProvider to encrypt or decrypt.
private byte[]	generateUniqueBytes()
private byte[]	Returns: the original unencrypted key bytes to use for encryption and decrytion getDatabaseSecretKey(Properties properties to retrieve the encrypted key properties, byte[] boot password used to connect to the encrypted database bootPassword, String errorstate to account for any errors during retrieval /creation of the secretKey errorState) get the secretkey used for encryption and decryption when boot password mechanism is used for encryption Steps include retrieve the stored key, decrypt the stored key and verify if the correct boot password was passed There is a possibility that the decrypted key includes the original key and padded bytes in order to have been block size aligned during encryption phase.
private byte[]	Returns: returns the hash value computed using the data getMD5Checksum(byte[] data to be used to compute the hash value data) Use MD5 MessageDigest algorithm to generate checksum
private byte[]	getMuckFromBootPassword(byte[] bootPassword, int encodedKeyByteLength)
public SecureRandom	getSecureRandom() Implements org.apache.derby.iapi.services.crypto.CipherFactory.getSecureRandom.
private byte[]	handleBootPassword(boolean create, Properties properties, boolean newPasswd)
private void	init(boolean create, Properties properties, boolean newAttrs)
private byte[]	Returns: a byte array with the contents of secretKey along with padded bytes in the end to make it blockSize aligned padKey(byte[] the data that needs blocksize alignment secretKey, int secretKey needs to be blocksize aligned blockSizeAlign) For block ciphers, and algorithms using the NoPadding scheme, the data that has to be encrypted needs to be a multiple of the expected block size for the cipher Pad the key with appropriate padding to make it blockSize align
private StorageRandomAccessFile	Returns: StorageRandomAccessFile returns file with fileName for writing privAccessFile(StorageFactory factory used for io access storageFactory, String name of the file to create and open for write The file will be created directly under the database root directory fileName, final String file permissions, if "rw" open file with read and write permissions if "r" , open file with read permissions filePerms) access a file for either read/write
private InputStream	Returns: InputStream returns the stream for the file with fileName for reading privAccessGetInputStream(StorageFactory factory used for io access storageFactory, String name of the file to open as a stream for reading fileName) access a InputStream for a given file for reading.
pack-priv static String	providerErrorName(String cps)
public void	saveProperties(Properties properties) Implements org.apache.derby.iapi.services.crypto.CipherFactory.saveProperties.
private String	saveSecretKey(byte[] secretKey, byte[] bootPassword)
public void	verifyKey(boolean true means database is being created, whereas false implies that the database has already been created create, StorageFactory storageFactory is used to access any stored data that might be needed for verification process of the encryption key sf, Properties properties at time of database connection as well as those in service.properties properties) Implements org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey. The database can be encrypted with an encryption key given in connection url.
private void	vetCipherProviders(CipherProvider decrypter, CipherProvider encrypter, String sqlState) Verify that a decrypter matches an encrypter.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

AES	back to summary
private static final String AES

AES_IV_LENGTH	back to summary
private static final int AES_IV_LENGTH AES encryption takes in an default Initialization vector length (IV) length of 16 bytes This is needed to generate an IV to use for encryption and decryption process See Also `CipherProvider`

BLOCK_LENGTH	back to summary
private static final int BLOCK_LENGTH

cryptoAlgorithm	back to summary
private String cryptoAlgorithm

cryptoAlgorithmShort	back to summary
private String cryptoAlgorithmShort

cryptoProvider	back to summary
private String cryptoProvider

cryptoProviderShort	back to summary
private String cryptoProviderShort

DEFAULT_ALGORITHM	back to summary
private static final String DEFAULT_ALGORITHM

DES	back to summary
private static final String DES

DESede	back to summary
private static final String DESede

encodedKeyLength	back to summary
private int encodedKeyLength

keyLengthBits	back to summary
private int keyLengthBits

mainIV	back to summary
private byte[] mainIV

mainSecretKey	back to summary
private SecretKey mainSecretKey

MESSAGE_DIGEST	back to summary
private static final String MESSAGE_DIGEST

messageDigest	back to summary
private MessageDigest messageDigest

persistentProperties	back to summary
private Properties persistentProperties

TripleDES	back to summary
private static final String TripleDES

VERIFYKEY_DATALEN	back to summary
private static final int VERIFYKEY_DATALEN Amount of data that is used for verification of external encryption key This does not include the MD5 checksum bytes

JCECipherFactory	back to summary
pack-priv JCECipherFactory(boolean create, Properties props, boolean newAttributes) throws StandardException

Method Detail

changeBootPassword	back to summary
public String changeBootPassword(String changeString, Properties properties, CipherProvider verify) throws StandardException Implements org.apache.derby.iapi.services.crypto.CipherFactory.changeBootPassword.

createNewCipher	back to summary
public CipherProvider createNewCipher(int mode) throws StandardException Implements org.apache.derby.iapi.services.crypto.CipherFactory.createNewCipher. Doc from org.apache.derby.iapi.services.crypto.CipherFactory.createNewCipher. Returns a CipherProvider which is the encryption or decryption engine. Parameters mode:int is either ENCRYPT or DECRYPT. The CipherProvider can only do encryption or decryption but not both. Returns:CipherProvider a cipher provider Exceptions StandardException: Standard Derby Error Policy

createNewCipher

back to summary

public CipherProvider createNewCipher(int mode) throws StandardException

Implements org.apache.derby.iapi.services.crypto.CipherFactory.createNewCipher.

Doc from org.apache.derby.iapi.services.crypto.CipherFactory.createNewCipher.

Returns a CipherProvider which is the encryption or decryption engine.

Parameters

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

Returns:CipherProvider

a cipher provider

Exceptions

StandardException:: Standard Derby Error Policy

createNewCipher	back to summary
private CipherProvider createNewCipher(int mode, SecretKey secretKey, byte[] iv) throws StandardException

decryptKey	back to summary
private byte[] decryptKey(String encryptedKey, int encodedKeyCharLength, byte[] bootPassword) throws StandardException Decrypt the secretKey with the user key . This includes the following steps, retrieve the encryptedKey, generate the muck from the boot password and generate an appropriate IV using the muck,and using the key and IV decrypt the encryptedKey Returns:byte[] decrypted key Exceptions StandardException: Standard Derby error policy

decryptKey

back to summary

private byte[] decryptKey(String encryptedKey, int encodedKeyCharLength, byte[] bootPassword) throws StandardException

Decrypt the secretKey with the user key . This includes the following steps, retrieve the encryptedKey, generate the muck from the boot password and generate an appropriate IV using the muck,and using the key and IV decrypt the encryptedKey

Returns:byte[]

decrypted key

Exceptions

StandardException:: Standard Derby error policy

digest	back to summary
private int digest(byte[] input)

encryptKey	back to summary
private JCECipherFactory.EncryptedKeyResult encryptKey(byte[] secretKey, byte[] bootPassword) throws StandardException Encrypt the secretKey with the boot password. This includes the following steps, getting muck from the boot password and then using this to generate a key, generating an appropriate IV using the muck using the key and IV thus generated to create the appropriate cipher provider and encrypting the secretKey Returns:JCECipherFactory.EncryptedKeyResult hexadecimal string of the encrypted secretKey Exceptions StandardException: Standard Derby error policy

encryptKey

back to summary

private JCECipherFactory.EncryptedKeyResult encryptKey(byte[] secretKey, byte[] bootPassword) throws StandardException

Encrypt the secretKey with the boot password. This includes the following steps, getting muck from the boot password and then using this to generate a key, generating an appropriate IV using the muck using the key and IV thus generated to create the appropriate cipher provider and encrypting the secretKey

Returns:JCECipherFactory.EncryptedKeyResult

hexadecimal string of the encrypted secretKey

Exceptions

StandardException:: Standard Derby error policy

generateIV	back to summary
private byte[] generateIV(byte[] secretKey) Generate an IV using the input secretKey that can be used by JCECipherProvider to encrypt or decrypt.

generateKey	back to summary
private SecretKey generateKey(byte[] secretKey) throws StandardException Generate a Key object using the input secretKey that can be used by JCECipherProvider to encrypt or decrypt. Exceptions StandardException: Standard Derby Error Policy

generateKey

back to summary

private SecretKey generateKey(byte[] secretKey) throws StandardException

Generate a Key object using the input secretKey that can be used by JCECipherProvider to encrypt or decrypt.

Exceptions

StandardException:: Standard Derby Error Policy

generateUniqueBytes	back to summary
private byte[] generateUniqueBytes() throws StandardException

getDatabaseSecretKey	back to summary
private byte[] getDatabaseSecretKey(Properties properties, byte[] bootPassword, String errorState) throws StandardException get the secretkey used for encryption and decryption when boot password mechanism is used for encryption Steps include retrieve the stored key, decrypt the stored key and verify if the correct boot password was passed There is a possibility that the decrypted key includes the original key and padded bytes in order to have been block size aligned during encryption phase. Hence extract the original key Parameters properties:Properties properties to retrieve the encrypted key bootPassword:byte[] boot password used to connect to the encrypted database errorState:String errorstate to account for any errors during retrieval /creation of the secretKey Returns:byte[] the original unencrypted key bytes to use for encryption and decrytion

getDatabaseSecretKey

back to summary

private byte[] getDatabaseSecretKey(Properties properties, byte[] bootPassword, String errorState) throws StandardException

get the secretkey used for encryption and decryption when boot password mechanism is used for encryption Steps include retrieve the stored key, decrypt the stored key and verify if the correct boot password was passed There is a possibility that the decrypted key includes the original key and padded bytes in order to have been block size aligned during encryption phase. Hence extract the original key

Parameters

properties:Properties: properties to retrieve the encrypted key
bootPassword:byte[]: boot password used to connect to the encrypted database
errorState:String: errorstate to account for any errors during retrieval /creation of the secretKey

Returns:byte[]

the original unencrypted key bytes to use for encryption and decrytion

getMD5Checksum	back to summary
private byte[] getMD5Checksum(byte[] data) throws StandardException Use MD5 MessageDigest algorithm to generate checksum Parameters data:byte[] data to be used to compute the hash value Returns:byte[] returns the hash value computed using the data

getMD5Checksum

back to summary

private byte[] getMD5Checksum(byte[] data) throws StandardException

Use MD5 MessageDigest algorithm to generate checksum

Parameters

data:byte[]: data to be used to compute the hash value

Returns:byte[]

returns the hash value computed using the data

getMuckFromBootPassword	back to summary
private byte[] getMuckFromBootPassword(byte[] bootPassword, int encodedKeyByteLength)

getSecureRandom	back to summary
public SecureRandom getSecureRandom() Implements org.apache.derby.iapi.services.crypto.CipherFactory.getSecureRandom.

handleBootPassword	back to summary
private byte[] handleBootPassword(boolean create, Properties properties, boolean newPasswd) throws StandardException

init	back to summary
private void init(boolean create, Properties properties, boolean newAttrs) throws StandardException

padKey	back to summary
private byte[] padKey(byte[] secretKey, int blockSizeAlign) For block ciphers, and algorithms using the NoPadding scheme, the data that has to be encrypted needs to be a multiple of the expected block size for the cipher Pad the key with appropriate padding to make it blockSize align Parameters secretKey:byte[] the data that needs blocksize alignment blockSizeAlign:int secretKey needs to be blocksize aligned Returns:byte[] a byte array with the contents of secretKey along with padded bytes in the end to make it blockSize aligned

padKey

back to summary

private byte[] padKey(byte[] secretKey, int blockSizeAlign)

For block ciphers, and algorithms using the NoPadding scheme, the data that has to be encrypted needs to be a multiple of the expected block size for the cipher Pad the key with appropriate padding to make it blockSize align

Parameters

secretKey:byte[]: the data that needs blocksize alignment
blockSizeAlign:int: secretKey needs to be blocksize aligned

Returns:byte[]

a byte array with the contents of secretKey along with padded bytes in the end to make it blockSize aligned

privAccessFile	back to summary
private StorageRandomAccessFile privAccessFile(StorageFactory storageFactory, String fileName, final String filePerms) throws IOException access a file for either read/write Parameters storageFactory:StorageFactory factory used for io access fileName:String name of the file to create and open for write The file will be created directly under the database root directory filePerms:String file permissions, if "rw" open file with read and write permissions if "r" , open file with read permissions Returns:StorageRandomAccessFile StorageRandomAccessFile returns file with fileName for writing Exceptions IOException: Any exception during accessing the file for read/write

privAccessFile

back to summary

private StorageRandomAccessFile privAccessFile(StorageFactory storageFactory, String fileName, final String filePerms) throws IOException

access a file for either read/write

Parameters

storageFactory:StorageFactory: factory used for io access
fileName:String: name of the file to create and open for write The file will be created directly under the database root directory
filePerms:String: file permissions, if "rw" open file with read and write permissions if "r" , open file with read permissions

Returns:StorageRandomAccessFile

StorageRandomAccessFile returns file with fileName for writing

Exceptions

IOException:: Any exception during accessing the file for read/write

privAccessGetInputStream	back to summary
private InputStream privAccessGetInputStream(StorageFactory storageFactory, String fileName) throws StandardException access a InputStream for a given file for reading. Parameters storageFactory:StorageFactory factory used for io access fileName:String name of the file to open as a stream for reading Returns:InputStream InputStream returns the stream for the file with fileName for reading Exceptions IOException: Any exception during accessing the file for read

privAccessGetInputStream

back to summary

private InputStream privAccessGetInputStream(StorageFactory storageFactory, String fileName) throws StandardException

access a InputStream for a given file for reading.

Parameters

storageFactory:StorageFactory: factory used for io access
fileName:String: name of the file to open as a stream for reading

Returns:InputStream

InputStream returns the stream for the file with fileName for reading

Exceptions

IOException:: Any exception during accessing the file for read

providerErrorName	back to summary
pack-priv static String providerErrorName(String cps)

saveProperties	back to summary
public void saveProperties(Properties properties) Implements org.apache.derby.iapi.services.crypto.CipherFactory.saveProperties.

saveSecretKey	back to summary
private String saveSecretKey(byte[] secretKey, byte[] bootPassword) throws StandardException

verifyKey	back to summary
public void verifyKey(boolean create, StorageFactory sf, Properties properties) throws StandardException Implements org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey. 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. Parameters create:boolean Doc from org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey. true means database is being created, whereas false implies that the database has already been created sf:StorageFactory Doc from org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey. storageFactory is used to access any stored data that might be needed for verification process of the encryption key properties:Properties Doc from org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey. properties at time of database connection as well as those in service.properties Exceptions StandardException: Doc from org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey. on error

verifyKey

back to summary

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

Implements org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey.

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.

Parameters

create:boolean

Doc from org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey.

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

sf:StorageFactory

Doc from org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey.

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

properties:Properties

Doc from org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey.

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

Exceptions

StandardException:

Doc from org.apache.derby.iapi.services.crypto.CipherFactory.verifyKey.

on error

vetCipherProviders	back to summary
private void vetCipherProviders(CipherProvider decrypter, CipherProvider encrypter, String sqlState) throws StandardException Verify that a decrypter matches an encrypter. Raises an exception if they don't. The verification is performed by encrypting a block of text and checking that it decrypts to the same block.

pack-priv final Class JCECipherFactory

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class JCECipherFactory.EncryptedKeyResult

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail