org.cumulus4j.store.model
Class EncryptionCoordinateSet

java.lang.Object
  org.cumulus4j.store.model.EncryptionCoordinateSet

public class EncryptionCoordinateSet
extends Object

Encryption coordinates used to encrypt a persistent record.

Via the EncryptionCoordinateSetManager, the CryptoManager (or CryptoSession) implementation can map the cipher-transformation and other encryption-coordinates (e.g. the MAC algorithm) to a number in order to save space in each persistent record.

Author:

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

Field Summary

static String

MAC_ALGORITHM_NONE Constant for deactivating the MAC.

Constructor Summary

protected	EncryptionCoordinateSet() Create a new EncryptionCoordinateSet.
protected	EncryptionCoordinateSet(String cipherTransformation, String macAlgorithm) Create a new EncryptionCoordinateSet.

Method Summary

static EncryptionCoordinateSet	createEncryptionCoordinateSet(PersistenceManager pm, String cipherTransformation, String macAlgorithm) Get an existing EncryptionCoordinateSet identified by its unique properties or create one if necessary.
String	getCipherTransformation() Get the cipher-transformation that identifies the encryption algorithm, the mode and the padding used to encrypt a record.
static EncryptionCoordinateSet	getEncryptionCoordinateSet(PersistenceManager pm, int encryptionCoordinateSetID) Get an existing EncryptionCoordinateSet identified by its encryptionCoordinateSetID.
static EncryptionCoordinateSet	getEncryptionCoordinateSet(PersistenceManager pm, String cipherTransformation, String macAlgorithm) Get an existing EncryptionCoordinateSet identified by its unique properties.
int	getEncryptionCoordinateSetID() Get the unique numeric identifier of this EncryptionCoordinateSet.
String	getMACAlgorithm() Get the MAC-algorithm used to protect a record against corruption/manipulation.

Methods inherited from class java.lang.Object

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

Field Detail

MAC_ALGORITHM_NONE

public 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 cipher-transformation already provides authentication - like GCM does for example.

See Also:

Constant Field Values

Constructor Detail

EncryptionCoordinateSet

protected EncryptionCoordinateSet()

Create a new EncryptionCoordinateSet. This default constructor only exists for JDO and should never be used directly!

EncryptionCoordinateSet

protected EncryptionCoordinateSet(String cipherTransformation,
                                  String macAlgorithm)

Create a new EncryptionCoordinateSet. Instead of using this constructor, you should use createEncryptionCoordinateSet(PersistenceManager, String, String)!

Parameters:

cipherTransformation - the cipher-transformation.

macAlgorithm - the MAC-algorithm.

Method Detail

getEncryptionCoordinateSet

public static EncryptionCoordinateSet getEncryptionCoordinateSet(PersistenceManager pm,
                                                                 int encryptionCoordinateSetID)

Get an existing EncryptionCoordinateSet identified by its encryptionCoordinateSetID.

Parameters:

pm - the backend-PersistenceManager (the one used for data, if there is a separate index-DB used).

encryptionCoordinateSetID - the identifier of the searched instance.

Returns:

the EncryptionCoordinateSet identified by the given encryptionCoordinateSetID or null, if no such instance exists in the datastore.

getEncryptionCoordinateSet

public static EncryptionCoordinateSet getEncryptionCoordinateSet(PersistenceManager pm,
                                                                 String cipherTransformation,
                                                                 String macAlgorithm)

Get an existing EncryptionCoordinateSet identified by its unique properties.

As each EncryptionCoordinateSet maps all encryption settings to an ID, all properties of this class except for the ID form a unique index together. At the moment, these are: cipher-transformation and MAC-algorithm.

Parameters:

pm - the backend-PersistenceManager (the one used for data, if there is a separate index-DB used).

cipherTransformation - the cipher-transformation of the searched instance. Must not be null.

macAlgorithm - the getMACAlgorithm() of the searched instance. Must not be null (use "NONE" for no MAC).

Returns:

the EncryptionCoordinateSet identified by the given properties or null, if no such instance exists in the datastore.

See Also:

createEncryptionCoordinateSet(PersistenceManager, String, String)

createEncryptionCoordinateSet

public static EncryptionCoordinateSet createEncryptionCoordinateSet(PersistenceManager pm,
                                                                    String cipherTransformation,
                                                                    String macAlgorithm)

Get an existing EncryptionCoordinateSet identified by its unique properties or create one if necessary.

This method is similar to getEncryptionCoordinateSet(PersistenceManager, String, String), but creates a new EncryptionCoordinateSet instead of returning null, if there is no existing instance, yet.

Parameters:

pm - the backend-PersistenceManager (the one used for data, if there is a separate index-DB used).

cipherTransformation - the cipher-transformation of the searched instance. Must not be null.

macAlgorithm - the getMACAlgorithm() of the searched instance. Must not be null (use "NONE" for no MAC).

Returns:

the EncryptionCoordinateSet identified by the given properties. This method never returns null, but instead creates and persists a new instance if needed.

See Also:

getEncryptionCoordinateSet(PersistenceManager, String, String)

getEncryptionCoordinateSetID

public int getEncryptionCoordinateSetID()

Get the unique numeric identifier of this EncryptionCoordinateSet.

Note: Implementors of CryptoManager (or CryptoSession respectively) might choose not to store the entire int value (4 bytes), but reduce the size. Every time the encryption configuration is changed, a new instance of this class is persisted. Restricting the size to 2 bytes, for example, still gives the administrator the possibility to change the configuration 65535 times - which is likely enough.

Returns:

the unique numeric identifier (primary key).

getCipherTransformation

public String getCipherTransformation()

Get the cipher-transformation that identifies the encryption algorithm, the mode and the padding used to encrypt a record. The system usually passes this value to CryptoRegistry.createCipher(String).

Returns:

the cipher-transformation. Never null.

getMACAlgorithm

public String getMACAlgorithm()

Get the MAC-algorithm used to protect a record against corruption/manipulation.

Implementors of CryptoManager/CryptoSession should take MAC_ALGORITHM_NONE into account! If this value equals that constant, MAC calculation and storage should be skipped.

Returns:

the MAC-algorithm.