org.cumulus4j.store.crypto
Interface CryptoManager

All Known Implementing Classes:

AbstractCryptoManager, DummyCryptoManager, KeyManagerCryptoManager

public interface CryptoManager

CryptoManagers allow the Cumulus4j-DataNucleus-plug-in to encrypt and decrypt data.

The primary purpose to make this feature pluggable is to provide different possibilities of the communication between the Cumulus4j-backend and a key store. For example, one client might prefer to manage the keys on the client while another client provides the coordinates of a key server to the backend.

There is one shared instance of CryptoManager per NucleusContext and cryptoManagerID. Due to this, instances of CryptoManager must be thread-safe!

A CryptoManager must not be instantiated directly, but instead obtained via CryptoManagerRegistry.getCryptoManager(String).

Important: It is strongly recommended to subclass AbstractCryptoManager instead of directly implementing this interface!

Author:

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

Field Summary

static String	MAC_ALGORITHM_NONE Constant for deactivating the MAC.
static String	PROPERTY_CRYPTO_MANAGER_ID Property-name used to pass the cryptoManagerID to the Cumulus4j-core.
static String	PROPERTY_CRYPTO_SESSION_EXPIRY_AGE Persistence property to control after which time an unused CryptoSession expires.
static String	PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED Persistence property to control whether the timer for cleaning up expired CryptoSessions is enabled.
static String	PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD Persistence property to control when the timer for cleaning up expired CryptoSessions is called.
static String	PROPERTY_ENCRYPTION_ALGORITHM Property to control the encryption algorithm that is used to encrypt data within the datastore.
static String	PROPERTY_MAC_ALGORITHM Property to control the MAC algorithm that is used to protect the data within the key-store against manipulation.

Method Summary

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.
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.

Field Detail

PROPERTY_CRYPTO_MANAGER_ID

static final String PROPERTY_CRYPTO_MANAGER_ID

Property-name used to pass the cryptoManagerID to the Cumulus4j-core.

The property can either be set in the persistence-unit/persistence-properties-file for the PersistenceManagerFactory/EntityManagerFactory or it can be passed via PersistenceManager.setProperty(String, Object) or EntityManager. If it is not set on the PM/EM level, the default-value set on the PMF/EMF level will be used.

See Also:

Constant Field Values

PROPERTY_ENCRYPTION_ALGORITHM

static final String PROPERTY_ENCRYPTION_ALGORITHM

Property to control the encryption algorithm that is used to encrypt data within the datastore. Both data and index are encrypted using this algorithm.

By default (if the property "cumulus4j.encryptionAlgorithm" is not specified), "Twofish/GCM/NoPadding" is used. For example, to switch to "AES/CFB/NoPadding", you'd have to specify "cumulus4j.encryptionAlgorithm=AES/CFB/NoPadding" in the persistence-unit/persistence-properties-file.

See this document for further information about what values are supported.

The encryption algorithm used during encryption is stored in the encryption-record's meta-data in order to use the correct algorithm during decryption, no matter what current encryption algorithm is configured. Therefore, you can safely change this setting at any time - it will affect future encryption operations, only.

Important: The default MAC algorithm is "NONE", which is a very bad choice for most encryption algorithms! Therefore, you must change the MAC algorithm via the property "cumulus4j.macAlgorithm" if you change the encryption algorithm!

The property can be set in the persistence-unit/persistence-properties-file for the PersistenceManagerFactory/EntityManagerFactory.

See Also:

getEncryptionAlgorithm(), Constant Field Values

PROPERTY_MAC_ALGORITHM

static final String PROPERTY_MAC_ALGORITHM

Property to control the MAC algorithm that is used to protect the data within the key-store against manipulation.

Whenever data is encrypted, this MAC algorithm is used to calculate a MAC over the original plain-text-data. The MAC is then stored together with the plain-text-data within the encrypted area. When data is decrypted, the MAC is calculated again over the decrypted plain-text-data and compared to the original MAC in order to make sure (1) that data was correctly decrypted [i.e. the key is correct] and (2) that the data in the datastore was not manipulated by an attacker.

The MAC algorithm used during encryption is stored in the encryption-record's meta-data in order to use the correct algorithm during decryption, no matter what current MAC algorithm is configured. Therefore, you can safely change this setting at any time - it will affect future encryption operations, only.

Some block cipher modes (e.g. GCM) already include authentication and therefore no MAC is necessary. In this case, you can specify the MAC algorithm "NONE".

Important: If you specify the MAC algorithm "NONE" and use an encryption algorithm without authentication, the key store will not be able to detect a wrong password and instead return corrupt data!!! Be VERY careful with the MAC algorithm "NONE"!!!

The default value (used when this system property is not specified) is "NONE", because the default encryption algorithm is "Twofish/GCM/NoPadding", which (due to "GCM") does not require an additional MAC.

The property can be set in the persistence-unit/persistence-properties-file for the PersistenceManagerFactory/EntityManagerFactory.

See Also:

getMACAlgorithm(), Constant Field Values

MAC_ALGORITHM_NONE

static final String MAC_ALGORITHM_NONE

Constant for deactivating the MAC.

Important: Deactivating the MAC is dangerous! Choose this value only, if you are absolutely sure that your encryption algorithm already provides authentication - like GCM does for example.

See Also:

PROPERTY_MAC_ALGORITHM, Constant Field Values

PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD

static final String PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD

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

If this persistence property is not present (or not a valid number > 0), the default is 60000 (1 minute), which means the timer will wake up once a minute and do the clean-up (default implementation is calling AbstractCryptoManager.closeExpiredCryptoSessions(boolean) with force = true).

If this persistence property is set to 0, the timer is deactivated and cleanup happens only synchronously when getCryptoSession(String) is called (periodically - not every time this method is called).

See Also:

PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED, Constant Field Values

PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED

static final String PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED

Persistence property to control whether the timer for cleaning up expired CryptoSessions is enabled. The value configured here is a boolean (i.e. must be "true" or "false"). The default value (if the property is not specified or incorrect) is "true".

See Also:

PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD, Constant Field Values

PROPERTY_CRYPTO_SESSION_EXPIRY_AGE

static final String PROPERTY_CRYPTO_SESSION_EXPIRY_AGE

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

CryptoSessions that are unused for the configured time in milliseconds are considered expired and either periodically removed by a timer (see property "cumulus4j.cryptoSessionExpiryTimer.period") or periodically removed synchronously during a call to getCryptoSession(String).

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

See Also:

Constant Field Values

Method Detail

getCryptoManagerRegistry

CryptoManagerRegistry getCryptoManagerRegistry()

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

Returns:

the registry holding this CryptoManager.

See Also:

setCryptoManagerRegistry(CryptoManagerRegistry)

setCryptoManagerRegistry

void setCryptoManagerRegistry(CryptoManagerRegistry cryptoManagerRegistry)

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

Parameters:

cryptoManagerRegistry -

See Also:

getCryptoManagerRegistry()

setCryptoManagerID

void setCryptoManagerID(String cryptoManagerID)

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!

Parameters:

cryptoManagerID - the identifier to set.

See Also:

getCryptoManagerID()

getCryptoManagerID

String getCryptoManagerID()

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 PROPERTY_CRYPTO_MANAGER_ID.

This method is thread-safe.

Returns:

the cryptoManagerID of this instance.

getCryptoSession

CryptoSession getCryptoSession(String cryptoSessionID)

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.

Parameters:

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

Returns:

the CryptoSession identified by the given identifier; never null.

onCloseCryptoSession

void onCloseCryptoSession(CryptoSession cryptoSession)

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().

Parameters:

cryptoSession - the session that is currently closed.

getEncryptionAlgorithm

String getEncryptionAlgorithm()

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

Returns:

the currently configured encryption algorithm.

See Also:

PROPERTY_ENCRYPTION_ALGORITHM

getMACAlgorithm

String getMACAlgorithm()

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

Returns:

the currently configured MAC algorithm.

See Also:

PROPERTY_MAC_ALGORITHM