|
Cumulus4j API (1.1.1) |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface CryptoSession
A CryptoSession
is a session in which key transfers can be performed.
Use KeyManagerAPI.getCryptoSession(String)
to get a CryptoSession
instance.
This instance is a proxy which can be kept and never expires (though the underlying real session will expire if
not used for some time). If the underlying real
session expired, a new underlying session with a new cryptoSessionID
will be created and bound to this CryptoSession
instance.
CryptoSession
s are thread-safe.
Method Summary | |
---|---|
String |
acquire()
Acquire an unlocked underlying real session. |
String |
getAppServerBaseURL()
Get the base-url of the app-server-key-manager-channel. |
String |
getAppServerID()
Get the identifier of the application server. |
void |
release()
Release the session, after it was previously acquired . |
Method Detail |
---|
String getAppServerID()
null
.String getAppServerBaseURL()
String acquire() throws AuthenticationException, IOException
Acquire an unlocked underlying real session.
The application server is only able to request keys from the key manager, while a crypto-session is acquired. It thus needs to be acquired, first, before it can be used for key transfers.
Important: It is essential that you call release()
once for every time you called acquire()
.
You should therefore use a try-finally-block like this:
String cryptoSessionID = session.acquire(); try { // Do some operation that requires key access. For example // call an EJB method or perform a SOAP/REST request which // will make your app server read/write data. } finally { session.release(); }
If multiple threads use the same CryptoSession
(recommended!), the underlying real session will be
acquired (unlocked) when the first thread requires it and it will be locked again when the last thread calls
release()
.
However, releasing (locking) does not need to happen immediately. Instead it can be deferred a few seconds, in
case a new acquire()
would happen quickly again. This
strategy is usually used with a remote key server (when latency makes acquiring/releasing a pretty expensive
operation).
AuthenticationException
- if the authentication fails. This might happen for example, when
a session was created and then the password was modified by another instance of KeyManagerAPI
.
Calling KeyManagerAPI.putUser(String, char[])
automatically updates the authentication information
of the current KeyManagerAPI
if the current user's password was changed. But if the password
is changed by another instance, this instance is locked out due to its outdated password.
IOException
- if communication with the key-store failed. This might be a socket error between
client and remote key server or it might be a problem when reading/writing data in the local file system.release()
void release() throws AuthenticationException, IOException
Release the session, after it was previously acquired
.
For every call to acquire()
, there must be exactly one call to release()
. You should
therefore use a try-finally-block!
See acquire()
for further details.
AuthenticationException
- if the authentication fails. This might happen for example, when
a session was created and then the password was modified by another instance of KeyManagerAPI
.
Calling KeyManagerAPI.putUser(String, char[])
automatically updates the authentication information
of the current KeyManagerAPI
if the current user's password was changed. But if the password
is changed by another instance, this instance is locked out due to its outdated password.
IOException
- if communication with the key-store failed. This might be a socket error between
client and remote key server or it might be a problem when reading/writing data in the local file system.acquire()
|
Cumulus4j API (1.1.1) |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |