Cumulus4j API
(1.0.0)

org.cumulus4j.store.crypto
Class AbstractCryptoManager

java.lang.Object
  extended by 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

Cumulus4j API
(1.0.0)

Copyright © 2012 NightLabs Consulting GmbH. All Rights Reserved.