|
Cumulus4j API (1.1.1) |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.cumulus4j.store.crypto.keymanager.CryptoCache
public class CryptoCache
Cache for secret keys, Cipher
s and other crypto-related objects.
There exists one instance of CryptoCache
per KeyManagerCryptoManager
.
This cache therefore holds objects across multiple sessions
.
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 |
---|
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
.
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
.
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).
Constructor Detail |
---|
public CryptoCache(KeyManagerCryptoManager cryptoManager)
CryptoCache
instance.
cryptoManager
- the owning CryptoManager
.Method Detail |
---|
public long getActiveEncryptionKeyID()
set
or the activeUntilExcl
has been reached (i.e. the previous active key expired),
this method returns -1.
setActiveEncryptionKeyID(long, Date)
public void setActiveEncryptionKeyID(long activeEncryptionKeyID, Date activeUntilExcl)
activeEncryptionKeyID
- identifier of the symmetric secret key that is currently active.activeUntilExcl
- timestamp until when (excluding) the specified key is active.getActiveEncryptionKeyID()
protected byte[] getKeyData(long keyID)
keyID
- identifier of the requested key.
null
, if the specified key is not cached.protected CryptoCacheKeyEntry setKeyData(long keyID, byte[] keyData)
keyID
- identifier of the key. Must be <= 0.keyData
- actual key. Must not be null
.
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!
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.
null
or an entry wrapping the desired cipher.acquireDecrypter(String, long, byte[], byte[])
,
releaseCipherEntry(CryptoCacheCipherEntry)
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!
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.
null
, if keyData
was specified.
If keyData == null
and the key is not cached, null
is returned.acquireDecrypter(String, long, byte[])
,
releaseCipherEntry(CryptoCacheCipherEntry)
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.
encryptionAlgorithm
- the encryption algorithm (the complete transformation as passed to CryptoRegistry.createCipher(String)
).keyID
- identifier of the key.
null
or an entry wrapping the desired cipher.acquireEncrypter(String, long, byte[])
,
releaseCipherEntry(CryptoCacheCipherEntry)
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.
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
.
null
, if keyData
was specified.
If keyData == null
and the key is not cached, null
is returned.acquireEncrypter(String, long)
,
releaseCipherEntry(CryptoCacheCipherEntry)
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.
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).acquireDecrypter(String, long, byte[])
,
acquireDecrypter(String, long, byte[], byte[])
,
acquireEncrypter(String, long)
,
acquireEncrypter(String, long, byte[])
public void clear()
protected long getKeyEncryptionKeyActivePeriodMSec()
getKeyEncryptionKey(String)
protected CryptoCacheKeyEncryptionKeyEntry getKeyEncryptionKey(String keyEncryptionTransformation)
keyEncryptionTransformation
- the transformation to be used for secret-key-encryption. Must not be null
.
public CryptoCacheKeyDecrypterEntry acquireKeyDecryptor(String keyEncryptionTransformation)
keyEncryptionKey
and can thus be directly used.
You should call releaseKeyDecryptor(CryptoCacheKeyDecrypterEntry)
to put the cipher back into the cache!
keyEncryptionTransformation
- the transformation to be used for secret-key-encryption. Must not be null
.
releaseKeyDecryptor(CryptoCacheKeyDecrypterEntry)
public void releaseKeyDecryptor(CryptoCacheKeyDecrypterEntry decryptorEntry)
decryptorEntry
- the entry to be released or null
(silently ignored).protected AsymmetricCipherKeyPairGenerator getAsymmetricCipherKeyPairGenerator(String keyEncryptionTransformation)
keyEncryptionTransformation
- the transformation (based on an asymmetric crypto algorithm) for which to obtain
a key-pair-generator.
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".
PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_PERIOD
,
PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_ENABLED
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".
PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_PERIOD
,
PROPERTY_CRYPTO_CACHE_CLEANUP_TIMER_ENABLED
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.
|
Cumulus4j API (1.1.1) |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |