org.cumulus4j.store.crypto
Interface CryptoSession

All Known Implementing Classes:

AbstractCryptoSession, KeyManagerCryptoSession

public interface CryptoSession

A CryptoSession is a session managed by a client to decrypt/encrypt data.

Data can only be decrypted (or encrypted) within the scope of a valid session. That means, the client must open a CryptoSession prior to persisting/querying data.

There exists one CryptoSession instance for each unique combination of NucleusContext, cryptoManagerID and cryptoSessionID. Therefore, it can happen, that multiple PersistenceManager/EntityManager instances access the same CryptoSession from multiple threads.

Thus all implementations of CryptoSession must be thread-safe! In this context, it is important to know that Cipher is not thread-safe! You should thus always synchronize on the Cipher instance before using it (if you share them, which you probably do due to the expensiveness of key-initialisations).

A CryptoSession must not be instantiated directly, but instead obtained via CryptoManager.getCryptoSession(String). In other words, a new instance of CryptoSession must only be created within the CryptoManager implementation.

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

Author:

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

Field Summary

static String

PROPERTY_CRYPTO_SESSION_ID Property-name used to pass the cryptoSessionID to the Cumulus4j-core.

Method Summary

void	close() Close the session.
Plaintext	decrypt(CryptoContext cryptoContext, Ciphertext ciphertext) Decrypt the given ciphertext.
Ciphertext	encrypt(CryptoContext cryptoContext, Plaintext plaintext) Encrypt the given plaintext.
Date	getCreationTimestamp()
CryptoManager	getCryptoManager() Get the CryptoManager to which this session belongs.
String	getCryptoSessionID()
Date	getLastUsageTimestamp() Get the timestamp of the last call to #release().
boolean	isClosed() Indicate, whether the session was already closed.
void	setCryptoManager(CryptoManager cryptoManager) Set the CryptoManager to which this session belongs.
void	setCryptoSessionID(String cryptoSessionID) Set the cryptoSessionID.
void	updateLastUsageTimestamp() Set the lastUsageTimestamp to now, i.e.

Field Detail

PROPERTY_CRYPTO_SESSION_ID

static final String PROPERTY_CRYPTO_SESSION_ID

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

The property must be passed to the Cumulus4j-core via PersistenceManager.setProperty(String, Object) or EntityManager.

See Also:

Constant Field Values

Method Detail

setCryptoManager

void setCryptoManager(CryptoManager cryptoManager)

Set the CryptoManager to which this session belongs.

If you subclass AbstractCryptoManager (instead of directly implementing the CryptoManager interface) you must never call this method. Otherwise, it is expected, that you call this method once in CryptoManager.getCryptoSession(String) after creating a new CryptoSession, before returning it.

Parameters:

cryptoManager - the CryptoManager to which this session belongs.

See Also:

getCryptoManager()

getCryptoManager

CryptoManager getCryptoManager()

Get the CryptoManager to which this session belongs.

Returns:

the CryptoManager to which this session belongs.

setCryptoSessionID

void setCryptoSessionID(String cryptoSessionID)

Set the cryptoSessionID.

If you subclass AbstractCryptoManager (instead of directly implementing the CryptoManager interface) you must never call this method. Otherwise, it is expected, that you call this method once in CryptoManager.getCryptoSession(String) after creating a new CryptoSession, before returning it.

Parameters:

cryptoSessionID - the identifier of this session.

See Also:

getCryptoSessionID()

getCryptoSessionID

String getCryptoSessionID()

getCreationTimestamp

Date getCreationTimestamp()

getLastUsageTimestamp

Date getLastUsageTimestamp()

Get the timestamp of the last call to #release(). If #release() was not yet called, get the time when this instance was created (just like getCreationTimestamp() does).

Therefore, this method always returns the time when the session was stopped being used the last time.

This timestamp is used for automatic closing of expired sessions.

Returns:

the timestamp of the last usage of this session.

updateLastUsageTimestamp

void updateLastUsageTimestamp()

Set the lastUsageTimestamp to now, i.e. new Date().

This method should be called by CryptoManager.getCryptoSession(String).

See Also:

getLastUsageTimestamp()

encrypt

Ciphertext encrypt(CryptoContext cryptoContext,
                   Plaintext plaintext)

Encrypt the given plaintext.

This method is thread-safe. Thus, implementors should keep in mind that Cipher is not thread-safe!

Parameters:

cryptoContext - context used to encrypt or decrypt data.

plaintext - the unencrypted information (aka plaintext) to be encrypted.

Returns:

the encrypted information (aka ciphertext).

decrypt

Plaintext decrypt(CryptoContext cryptoContext,
                  Ciphertext ciphertext)

Decrypt the given ciphertext.

This method is thread-safe. Thus, implementors should keep in mind that Cipher is not thread-safe!

Parameters:

cryptoContext - context used to encrypt or decrypt data.

ciphertext - the encrypted information (aka ciphertext) to be decrypted.

Returns:

the unencrypted information (aka plaintext).

close

void close()

Close the session.

After closing, the CryptoSession cannot be used for encryption/decryption anymore, i.e. encrypt(CryptoContext, Plaintext) and decrypt(CryptoContext, Ciphertext) very likely throw an exception. The other methods might still work.

This method can be called multiple times - every following call will be silently ignored.

isClosed

boolean isClosed()

Indicate, whether the session was already closed.

Returns:

true, if close() was already called; false otherwise.