org.cumulus4j.store.crypto.keymanager
Class CryptoCache

java.lang.Object
  org.cumulus4j.store.crypto.keymanager.CryptoCache

public class CryptoCache
extends Object

Cache for secret keys, Ciphers and other crypto-related objects.

There exists one instance of CryptoCache per KeyManagerCryptoManager. This cache therefore holds objects across multiple sessions.

Author:

Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de

Field Summary

static String	PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_ENABLED Persistence property to control whether the timer for cleaning up expired CryptoCache-entries is enabled.
static String	PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_PERIOD Persistence property to control when the timer for cleaning up expired CryptoCache-entries is called.
static String	PROPERTY_CRYPTO_CACHE_ENTRY_EXPIRY_AGE Persistence property to control after which time an unused entry expires.

Constructor Summary

CryptoCache(KeyManagerCryptoManager cryptoManager)
Create a CryptoCache instance.

Method Summary

CryptoCacheCipherEntry	acquireDecrypter(String cipherTransformation, long keyID, byte[] iv) Acquire a decrypter and initialise it so that it is ready to be used.
CryptoCacheCipherEntry	acquireDecrypter(String encryptionAlgorithm, long keyID, byte[] keyData, byte[] iv) Acquire a decrypter and initialise it so that it is ready to be used.
CryptoCacheCipherEntry	acquireEncrypter(String encryptionAlgorithm, long keyID) Acquire an encrypter and initialise it so that it is ready to be used.
CryptoCacheCipherEntry	acquireEncrypter(String cipherTransformation, long keyID, byte[] keyData) Acquire an encrypter and initialise it so that it is ready to be used.
CryptoCacheKeyDecrypterEntry	acquireKeyDecryptor(String keyEncryptionTransformation) Acquire a cipher to be used for secret-key-decryption.
void	clear() Clear this cache entirely.
long	getActiveEncryptionKeyID() Get the currently active encryption key.
protected AsymmetricCipherKeyPairGenerator	getAsymmetricCipherKeyPairGenerator(String keyEncryptionTransformation) Get a key-pair-generator for the given transformation.
protected boolean	getCleanupTimerEnabled() Get the enabled status of the timer used to cleanup.
protected long	getCleanupTimerPeriod() Get the period in which expired entries are searched and closed.
protected long	getCryptoCacheEntryExpiryAge() Get the age after which an unused entry expires.
protected byte[]	getKeyData(long keyID) Get the actual key data for the given key identifier.
protected CryptoCacheKeyEncryptionKeyEntry	getKeyEncryptionKey(String keyEncryptionTransformation) Get the key-pair that is currently active for secret-key-encryption.
protected long	getKeyEncryptionKeyActivePeriodMSec() How long should the public-private-key-pair for secret-key-encryption be used.
void	releaseCipherEntry(CryptoCacheCipherEntry cipherEntry) Release a Cipher wrapped in the given entry.
void	releaseKeyDecryptor(CryptoCacheKeyDecrypterEntry decryptorEntry) Release a cipher (put it back into the cache).
void	setActiveEncryptionKeyID(long activeEncryptionKeyID, Date activeUntilExcl) Set the currently active encryption key.
protected CryptoCacheKeyEntry	setKeyData(long keyID, byte[] keyData) Put a certain key into this cache.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_PERIOD

public static final String PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_PERIOD

Persistence property to control when the timer for cleaning up expired CryptoCache-entries is called. The value configured here is a period in milliseconds, i.e. the timer will be triggered every X ms (roughly).

If this persistence property is not present (or not a valid number), the default is 60000 (1 minute), which means the timer will wake up once a minute and call removeExpiredEntries(boolean) with force = true.

See Also:

Constant Field Values

PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_ENABLED

public static final String PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_ENABLED

Persistence property to control whether the timer for cleaning up expired CryptoCache-entries is enabled. The value configured here can be either true or false.

If this persistence property is not present (or not a valid number), the default is true, which means the timer is enabled and will periodically call removeExpiredEntries(boolean) with force = true.

If this persistence property is set to false, the timer is deactivated and cleanup happens only synchronously when one of the release-methods is called; periodically - not every time a method is called. The period is in this case the same as for the timer, i.e. configurable via PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_PERIOD.

See Also:

Constant Field Values

PROPERTY_CRYPTO_CACHE_ENTRY_EXPIRY_AGE

public static final String PROPERTY_CRYPTO_CACHE_ENTRY_EXPIRY_AGE

Persistence property to control after which time an unused entry expires.

Entries that are unused for the configured time in milliseconds are considered expired and either periodically removed by a timer (see property "cumulus4j.CryptoCache.cleanupTimer.period") or periodically removed synchronously during a call to one of the release-methods.

If this property is not present (or not a valid number), the default value is 1800000 (30 minutes).

See Also:

Constant Field Values

Constructor Detail

CryptoCache

public CryptoCache(KeyManagerCryptoManager cryptoManager)

Create a CryptoCache instance.

Parameters:

cryptoManager - the owning CryptoManager.

Method Detail

getActiveEncryptionKeyID

public long getActiveEncryptionKeyID()

Get the currently active encryption key. If there has none yet be set or the activeUntilExcl has been reached (i.e. the previous active key expired), this method returns -1.

Returns:

the currently active encryption key or -1, if there is none.

See Also:

setActiveEncryptionKeyID(long, Date)

setActiveEncryptionKeyID

public void setActiveEncryptionKeyID(long activeEncryptionKeyID,
                                     Date activeUntilExcl)

Set the currently active encryption key.

Parameters:

activeEncryptionKeyID - identifier of the symmetric secret key that is currently active.

activeUntilExcl - timestamp until when (excluding) the specified key is active.

See Also:

getActiveEncryptionKeyID()

getKeyData

protected byte[] getKeyData(long keyID)

Get the actual key data for the given key identifier.

Parameters:

keyID - identifier of the requested key.

Returns:

actual key data or null, if the specified key is not cached.

setKeyData

protected CryptoCacheKeyEntry setKeyData(long keyID,
                                         byte[] keyData)

Put a certain key into this cache.

Parameters:

keyID - identifier of the key. Must be <= 0.

keyData - actual key. Must not be null.

Returns:

the immutable entry for the given key in this cache.

acquireDecrypter

public CryptoCacheCipherEntry acquireDecrypter(String cipherTransformation,
                                               long keyID,
                                               byte[] iv)

Acquire a decrypter and initialise it so that it is ready to be used.

This method can only return a Cipher, if there is one cached, already, or at least the key is cached so that a new Cipher can be created. If there is neither a cipher nor a key cached, this method returns null. The key - if found - is refreshed (with the current timestamp) by this operation and will thus be evicted later.

Important: You must use a try-finally-block ensuring that releaseCipherEntry(CryptoCacheCipherEntry) is called!

Parameters:

cipherTransformation - the encryption algorithm (the complete transformation as passed to CryptoRegistry.createCipher(String)).

keyID - identifier of the key.

iv - initialisation vector. Must be the same as the one that was used for encryption.

Returns:

null or an entry wrapping the desired cipher.

See Also:

acquireDecrypter(String, long, byte[], byte[]), releaseCipherEntry(CryptoCacheCipherEntry)

acquireDecrypter

public CryptoCacheCipherEntry acquireDecrypter(String encryptionAlgorithm,
                                               long keyID,
                                               byte[] keyData,
                                               byte[] iv)

Acquire a decrypter and initialise it so that it is ready to be used.

This method returns an existing Cipher, if there is one cached, already. Otherwise a new Cipher is created. The key is added (with the current timestamp) into the cache.

Important: You must use a try-finally-block ensuring that releaseCipherEntry(CryptoCacheCipherEntry) is called!

Parameters:

encryptionAlgorithm - the encryption algorithm (the complete transformation as passed to CryptoRegistry.createCipher(String)).

keyID - identifier of the key.

keyData - the actual key. If it is null, the key is fetched from the cache. If it is not cached, this method returns null.

iv - initialisation vector. Must be the same as the one that was used for encryption.

Returns:

an entry wrapping the desired cipher. Never returns null, if keyData was specified. If keyData == null and the key is not cached, null is returned.

See Also:

acquireDecrypter(String, long, byte[]), releaseCipherEntry(CryptoCacheCipherEntry)

acquireEncrypter

public CryptoCacheCipherEntry acquireEncrypter(String encryptionAlgorithm,
                                               long keyID)

Acquire an encrypter and initialise it so that it is ready to be used.

This method can only return a Cipher, if there is one cached, already, or at least the key is cached so that a new Cipher can be created. If there is neither a cipher nor a key cached, this method returns null. The key - if found - is refreshed (with the current timestamp) by this operation and will thus be evicted later.

You should use a try-finally-block ensuring that releaseCipherEntry(CryptoCacheCipherEntry) is called!

This method generates a random IV (initialisation vector) every time it is called. The IV can be obtained via Cipher.getParameters() and casting the result to ParametersWithIV. The IV is required for decryption.

Parameters:

encryptionAlgorithm - the encryption algorithm (the complete transformation as passed to CryptoRegistry.createCipher(String)).

keyID - identifier of the key.

Returns:

null or an entry wrapping the desired cipher.

See Also:

acquireEncrypter(String, long, byte[]), releaseCipherEntry(CryptoCacheCipherEntry)

acquireEncrypter

public CryptoCacheCipherEntry acquireEncrypter(String cipherTransformation,
                                               long keyID,
                                               byte[] keyData)

Acquire an encrypter and initialise it so that it is ready to be used.

This method returns an existing Cipher, if there is one cached, already. Otherwise a new Cipher is created. The key is added (with the current timestamp) into the cache.

You should use a try-finally-block ensuring that releaseCipherEntry(CryptoCacheCipherEntry) is called!

This method generates a random IV (initialisation vector) every time it is called. The IV can be obtained via Cipher.getParameters() and casting the result to ParametersWithIV. The IV is required for decryption.

Parameters:

cipherTransformation - the encryption algorithm (the complete transformation as passed to CryptoRegistry.createCipher(String)).

keyID - identifier of the key.

keyData - the actual key. If it is null, the key is fetched from the cache. If it is not cached, this method returns null.

Returns:

an entry wrapping the desired cipher. Never returns null, if keyData was specified. If keyData == null and the key is not cached, null is returned.

See Also:

acquireEncrypter(String, long), releaseCipherEntry(CryptoCacheCipherEntry)

releaseCipherEntry

public void releaseCipherEntry(CryptoCacheCipherEntry cipherEntry)

Release a Cipher wrapped in the given entry.

This should be called in a finally block ensuring that the Cipher is put back into the cache.

Parameters:

cipherEntry - the entry to be put back into the cache or null, if it was not yet assigned. This method accepts null as argument to make usage in a try-finally-block easier and less error-prone (no null-checks required).

See Also:

acquireDecrypter(String, long, byte[]), acquireDecrypter(String, long, byte[], byte[]), acquireEncrypter(String, long), acquireEncrypter(String, long, byte[])

clear

public void clear()

Clear this cache entirely. This evicts all cached objects - no matter what type.

getKeyEncryptionKeyActivePeriodMSec

protected long getKeyEncryptionKeyActivePeriodMSec()

How long should the public-private-key-pair for secret-key-encryption be used. After that time, a new public-private-key-pair is generated.

Returns:

the time a public-private-key-pair should be used.

See Also:

getKeyEncryptionKey(String)

getKeyEncryptionKey

protected CryptoCacheKeyEncryptionKeyEntry getKeyEncryptionKey(String keyEncryptionTransformation)

Get the key-pair that is currently active for secret-key-encryption.

Parameters:

keyEncryptionTransformation - the transformation to be used for secret-key-encryption. Must not be null.

Returns:

entry wrapping the key-pair that is currently active for secret-key-encryption.

acquireKeyDecryptor

public CryptoCacheKeyDecrypterEntry acquireKeyDecryptor(String keyEncryptionTransformation)

Acquire a cipher to be used for secret-key-decryption. The cipher is already initialised with the current keyEncryptionKey and can thus be directly used.

You should call releaseKeyDecryptor(CryptoCacheKeyDecrypterEntry) to put the cipher back into the cache!

Parameters:

keyEncryptionTransformation - the transformation to be used for secret-key-encryption. Must not be null.

Returns:

entry wrapping the cipher that is ready to be used for secret-key-decryption.

See Also:

releaseKeyDecryptor(CryptoCacheKeyDecrypterEntry)

releaseKeyDecryptor

public void releaseKeyDecryptor(CryptoCacheKeyDecrypterEntry decryptorEntry)

Release a cipher (put it back into the cache).

Parameters:

decryptorEntry - the entry to be released or null (silently ignored).

getAsymmetricCipherKeyPairGenerator

protected AsymmetricCipherKeyPairGenerator getAsymmetricCipherKeyPairGenerator(String keyEncryptionTransformation)

Get a key-pair-generator for the given transformation.

Parameters:

keyEncryptionTransformation - the transformation (based on an asymmetric crypto algorithm) for which to obtain a key-pair-generator.

Returns:

the key-pair-generator.

getCleanupTimerPeriod

protected long getCleanupTimerPeriod()

Get the period in which expired entries are searched and closed.

This value can be configured using the persistence property "cumulus4j.CryptoCache.cleanupTimer.period".

Returns:

the period in milliseconds.

See Also:

PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_PERIOD, PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_ENABLED

getCleanupTimerEnabled

protected boolean getCleanupTimerEnabled()

Get the enabled status of the timer used to cleanup.

This value can be configured using the persistence property "cumulus4j.CryptoCache.cleanupTimer.enabled".

Returns:

the enabled status.

See Also:

PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_PERIOD, PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_ENABLED

getCryptoCacheEntryExpiryAge

protected long getCryptoCacheEntryExpiryAge()

Get the age after which an unused entry expires.

An entry expires when its lastUsageTimestamp is longer in the past than this expiry age. Note, that the entry might be kept longer, because a timer checks periodically for expired entries.

Returns:

the expiry age (of non-usage-time) in milliseconds, after which an entry should be expired (and thus removed).