org.cumulus4j.keymanager.api.internal.remote
Class RemoteCryptoSession

java.lang.Object
  org.cumulus4j.keymanager.api.internal.remote.RemoteCryptoSession

All Implemented Interfaces:

CryptoSession

public class RemoteCryptoSession
extends Object
implements CryptoSession

Author:

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

Constructor Summary

RemoteCryptoSession(RemoteKeyManagerAPI remoteKeyManagerAPI, AppServer appServer)

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.

Methods inherited from class java.lang.Object

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

Constructor Detail

RemoteCryptoSession

public RemoteCryptoSession(RemoteKeyManagerAPI remoteKeyManagerAPI,
                           AppServer appServer)

Method Detail

getAppServerID

public String getAppServerID()

Description copied from interface: CryptoSession

Get the identifier of the application server. This denotes a logical application server, which can be composed of many physical machines (in a cluster/cloud).

Specified by:

getAppServerID in interface CryptoSession

Returns:

the application server's ID; never null.

getAppServerBaseURL

public String getAppServerBaseURL()

Description copied from interface: CryptoSession

Get the base-url of the app-server-key-manager-channel. This is the part of the URL before the "/KeyManagerChannel" - e.g. if the REST URL of the KeyManagerChannel-service is "https://serverUsingCumulus4j.mydomain.org/org.cumulus4j.keymanager.back.webapp/KeyManagerChannel", then this must be "https://serverUsingCumulus4j.mydomain.org/org.cumulus4j.keymanager.back.webapp".

Specified by:

getAppServerBaseURL in interface CryptoSession

Returns:

the base-URL before the "/KeyManagerChannel".

release

public void release()
             throws AuthenticationException,
                    IOException

Description copied from interface: CryptoSession

Release the session, after it was previously acquired.

For every call to CryptoSession.acquire(), there must be exactly one call to CryptoSession.release(). You should therefore use a try-finally-block!

See CryptoSession.acquire() for further details.

Specified by:

release in interface CryptoSession

Throws:

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.

See Also:

CryptoSession.acquire()

acquire

public String acquire()
               throws AuthenticationException,
                      IOException

Description copied from interface: CryptoSession

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

Specified by:

acquire in interface CryptoSession

Returns:

the cryptoSessionID to be used within the acquire-release-block for key-management. This ID must be passed to your application server in order to allow it perform database operations.

Throws:

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.

See Also:

CryptoSession.release()