org.cumulus4j.store.crypto
Class AbstractCryptoManager

java.lang.Object
  org.cumulus4j.store.crypto.AbstractCryptoManager

All Implemented Interfaces:

CryptoManager

Direct Known Subclasses:

DummyCryptoManager, KeyManagerCryptoManager

public abstract class AbstractCryptoManager
extends Object
implements CryptoManager

Abstract base-class for implementing CryptoManagers.

This class already implements a mechanism to close expired CryptoSessions periodically (see getCryptoSessionExpiryAge() and getCryptoSessionExpiryTimerPeriod()).

Author:

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

Field Summary

Fields inherited from interface org.cumulus4j.store.crypto.CryptoManager

MAC_ALGORITHM_NONE, PROPERTY_CRYPTO_MANAGER_ID, PROPERTY_CRYPTO_SESSION_EXPIRY_AGE, PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED, PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD, PROPERTY_ENCRYPTION_ALGORITHM, PROPERTY_MAC_ALGORITHM

Constructor Summary

AbstractCryptoManager()

Method Summary

protected void	closeExpiredCryptoSessions(boolean force) Close expired CryptoSessions.
protected abstract CryptoSession	createCryptoSession() Create a new instance of a class implementing CryptoSession.
String	getCryptoManagerID() Get the cryptoManagerID of this instance.
CryptoManagerRegistry	getCryptoManagerRegistry() Get the registry which manages this CryptoManager.
CryptoSession	getCryptoSession(String cryptoSessionID) Get the CryptoSession identified by the given cryptoSessionID.
protected long	getCryptoSessionExpiryAge() Get the age after which an unused session expires.
protected boolean	getCryptoSessionExpiryTimerEnabled() Get the enabled status of the timer used to cleanup.
protected long	getCryptoSessionExpiryTimerPeriod() Get the period in which expired crypto sessions are searched and closed.
String	getEncryptionAlgorithm() Get the value of the property "cumulus4j.encryptionAlgorithm".
String	getMACAlgorithm() Get the value of the property "cumulus4j.macAlgorithm".
void	onCloseCryptoSession(CryptoSession cryptoSession) Notify the CryptoManager about the fact that a session is currently being closed.
void	setCryptoManagerID(String cryptoManagerID) Set the cryptoManagerID of this instance.
void	setCryptoManagerRegistry(CryptoManagerRegistry cryptoManagerRegistry) Set the registry which manages this CryptoManager.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractCryptoManager

public AbstractCryptoManager()

Method Detail

getCryptoSessionExpiryTimerPeriod

protected long getCryptoSessionExpiryTimerPeriod()

Get the period in which expired crypto sessions are searched and closed.

This value can be configured using the persistence property .

Returns:

the period in milliseconds.

See Also:

CryptoManager.PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD, CryptoManager.PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED

getCryptoSessionExpiryTimerEnabled

protected boolean getCryptoSessionExpiryTimerEnabled()

Get the enabled status of the timer used to cleanup.

This value can be configured using the persistence property .

Returns:

the enabled status.

See Also:

CryptoManager.PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED, CryptoManager.PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD

getCryptoSessionExpiryAge

protected long getCryptoSessionExpiryAge()

Get the age after which an unused session expires.

This value can be configured using the persistence property .

A CryptoSession expires when its lastUsageTimestamp is longer in the past than this expiry age. Note, that the session might be kept longer, because a timer checks periodically for expired sessions.

Returns:

the expiry age (of non-usage-time) in milliseconds, after which the session should be closed.

See Also:

CryptoManager.PROPERTY_CRYPTO_SESSION_EXPIRY_AGE

closeExpiredCryptoSessions

protected void closeExpiredCryptoSessions(boolean force)

Close expired CryptoSessions. If force == false, it does so only periodically.

This method is called by getCryptoSession(String) with force == false, if the timer is disabled timer-period == 0. If the timer is enabled, it is called periodically by the timer with force == true.

Parameters:

force - whether to force the cleanup now or only do it periodically.

See Also:

CryptoManager.PROPERTY_CRYPTO_SESSION_EXPIRY_AGE, CryptoManager.PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD

getCryptoManagerRegistry

public CryptoManagerRegistry getCryptoManagerRegistry()

Description copied from interface: CryptoManager

Get the registry which manages this CryptoManager. This method should normally never return null, because the registry is set immediately after instantiation.

Specified by:

getCryptoManagerRegistry in interface CryptoManager

Returns:

the registry holding this CryptoManager.

See Also:

CryptoManager.setCryptoManagerRegistry(CryptoManagerRegistry)

setCryptoManagerRegistry

public void setCryptoManagerRegistry(CryptoManagerRegistry cryptoManagerRegistry)

Description copied from interface: CryptoManager

Set the registry which manages this CryptoManager. This method is called by the CryptoManagerRegistry whenever it creates a new instance of CryptoManager.

Specified by:

setCryptoManagerRegistry in interface CryptoManager

See Also:

CryptoManager.getCryptoManagerRegistry()

getCryptoManagerID

public String getCryptoManagerID()

Description copied from interface: CryptoManager

Get the cryptoManagerID of this instance.

The cryptoManagerID is configured in the plugin.xml when registering an extension to the extension-point org.cumulus4j.api.cryptoManager. It is then used by the client to specify which method of key-exchange (or key-management in general) and encryption/decryption is desired. This is done by setting the property CryptoManager.PROPERTY_CRYPTO_MANAGER_ID.

This method is thread-safe.

Specified by:

getCryptoManagerID in interface CryptoManager

Returns:

the cryptoManagerID of this instance.

setCryptoManagerID

public void setCryptoManagerID(String cryptoManagerID)

Description copied from interface: CryptoManager

Set the cryptoManagerID of this instance.

This method is called with the value configured in the plugin.xml directly after instantiating the CryptoManager.

You must never directly call this method! It is not an API method!

Specified by:

setCryptoManagerID in interface CryptoManager

Parameters:

cryptoManagerID - the identifier to set.

See Also:

CryptoManager.getCryptoManagerID()

createCryptoSession

protected abstract CryptoSession createCryptoSession()

Create a new instance of a class implementing CryptoSession.

This method is called by getCryptoSession(String), if it needs a new CryptoSession instance.

Implementors should simply instantiate and return their implementation of CryptoSession. It is not necessary to call CryptoSession.setCryptoSessionID(String) and the like here - this is automatically done afterwards by getCryptoSession(String).

Returns:

the new CryptoSession instance.

getCryptoSession

public CryptoSession getCryptoSession(String cryptoSessionID)

Description copied from interface: CryptoManager

Get the CryptoSession identified by the given cryptoSessionID.

Usually, every client opens one crypto-session. How exactly this happens, is highly dependent on the CryptoManager and CryptoSession implementation. The cryptoSessionID is then passed from the client to the server which itself passes it to the PersistenceManager (or EntityManager) via the property with the name CryptoSession.PROPERTY_CRYPTO_SESSION_ID.

Calling this method with a non-existing cryptoSessionID implicitely creates a CryptoSession instance and returns it. A future call to this method with the same cryptoSessionID returns the same CryptoSession instance.

A CryptoSession should only be kept in the memory of a CryptoManager for a limited time. It is recommended to remove it a short configurable time (e.g. 10 minutes) after the last usage.

This method must call CryptoSession.updateLastUsageTimestamp().

This method is thread-safe.

Specified by:

getCryptoSession in interface CryptoManager

Parameters:

cryptoSessionID - the cryptoSessionID for which to look up or create a CryptoSession.

Returns:

the CryptoSession identified by the given identifier; never null.

onCloseCryptoSession

public void onCloseCryptoSession(CryptoSession cryptoSession)

Description copied from interface: CryptoManager

Notify the CryptoManager about the fact that a session is currently being closed.

Important: This method must never be called directly! It must be called by CryptoSession.close().

Specified by:

onCloseCryptoSession in interface CryptoManager

Parameters:

cryptoSession - the session that is currently closed.

getEncryptionAlgorithm

public String getEncryptionAlgorithm()

Description copied from interface: CryptoManager

Get the value of the property "cumulus4j.encryptionAlgorithm". This property can be configured in the persistence-unit/persistence-properties-file.

Specified by:

getEncryptionAlgorithm in interface CryptoManager

Returns:

the currently configured encryption algorithm.

See Also:

CryptoManager.PROPERTY_ENCRYPTION_ALGORITHM

getMACAlgorithm

public String getMACAlgorithm()

Description copied from interface: CryptoManager

Get the value of the property "cumulus4j.macAlgorithm". This property can be configured in the persistence-unit/persistence-properties-file.

Specified by:

getMACAlgorithm in interface CryptoManager

Returns:

the currently configured MAC algorithm.

See Also:

CryptoManager.PROPERTY_MAC_ALGORITHM