|
Cumulus4j API (1.1.0) |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface CryptoManager
CryptoManager
s 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!
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 CryptoSession s is enabled. |
static String |
PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD
Persistence property to control when the timer for cleaning up expired CryptoSession s 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 |
---|
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.
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
.
getEncryptionAlgorithm()
,
Constant Field Valuesstatic 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
.
getMACAlgorithm()
,
Constant Field Valuesstatic 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.
PROPERTY_MAC_ALGORITHM
,
Constant Field Valuesstatic final String PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD
Persistence property to control when the timer for cleaning up expired CryptoSession
s 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).
PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED
,
Constant Field Valuesstatic final String PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED
CryptoSession
s 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".
PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD
,
Constant Field Valuesstatic final String PROPERTY_CRYPTO_SESSION_EXPIRY_AGE
Persistence property to control after which time an unused CryptoSession
expires.
CryptoSession
s 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).
Method Detail |
---|
CryptoManagerRegistry getCryptoManagerRegistry()
CryptoManager
.
This method should normally never return null
, because
the registry is set
immediately
after instantiation.
CryptoManager
.setCryptoManagerRegistry(CryptoManagerRegistry)
void setCryptoManagerRegistry(CryptoManagerRegistry cryptoManagerRegistry)
CryptoManager
.
This method is called by the CryptoManagerRegistry
whenever
it creates a new instance of CryptoManager
.
cryptoManagerRegistry
- getCryptoManagerRegistry()
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!
cryptoManagerID
- the identifier to set.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.
cryptoManagerID
of this instance.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.
cryptoSessionID
- the cryptoSessionID
for which to look up or
create a CryptoSession
.
CryptoSession
identified by the given identifier; never null
.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()
.
cryptoSession
- the session that is currently closed.String getEncryptionAlgorithm()
PROPERTY_ENCRYPTION_ALGORITHM
String getMACAlgorithm()
PROPERTY_MAC_ALGORITHM
|
Cumulus4j API (1.1.0) |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |