org.cumulus4j.keymanager.api
Interface KeyManagerAPI

All Known Implementing Classes:

AbstractKeyManagerAPI, DefaultKeyManagerAPI, LocalKeyManagerAPI, RemoteKeyManagerAPI

public interface KeyManagerAPI

Entry point for the key management API.

Use new DefaultKeyManagerAPI() to get an instance, which you should keep (e.g. in a static shared instance or some other context). Except for this one reference to DefaultKeyManagerAPI (i.e. an implementation class), you should only reference the interfaces of this API project!

An application server using Cumulus4j is only able to read or write data, when the key manager grants access to keys. In order to control this access, crypto-sessions are used (not to be confused with a servlet's session): An application server can only request a key from a key manager, when the crypto-session exists and is unlocked. Usually, a client will first unlock the session, then send a request to the app server and when the app server responded, lock the session, again. Thus most of the time, a key manager will reject access to keys, even while a connection between app server and key manager exists.

This entire API (all classes in org.cumulus4j.keymanager.api) is thread-safe. You can - and should - share one KeyManagerAPI instance across multiple threads.

Note, that you must configure the KeyManagerAPI, before you can use it.

Author:

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

Method Summary

void	deleteUser(String userName) Delete a user.
KeyManagerAPIConfiguration	getConfiguration() Get the current configuration of this KeyManagerAPI.
CryptoSession	getCryptoSession(String appServerBaseURL) Get a session for a certain application server.
DateDependentKeyStrategyInitResult	initDateDependentKeyStrategy(DateDependentKeyStrategyInitParam param) Initialise a new key-store with the DateDependentKeyStrategy.
void	putUser(String userName, char[] password) Create a new user or change an existing user's password.
void	setConfiguration(KeyManagerAPIConfiguration configuration) Set the configuration for this KeyManagerAPI instance.

Method Detail

setConfiguration

void setConfiguration(KeyManagerAPIConfiguration configuration)
                      throws IllegalArgumentException,
                             KeyManagerAPIInstantiationException

Set the configuration for this KeyManagerAPI instance.

Before a KeyManagerAPI instance can actually be used, it first needs to be configured. The configuration passed to this method will be marked read-only.

Parameters:

configuration - the configuration (which will be marked read-only by this operation). Must not be null.

Throws:

IllegalArgumentException - if the configuration is null or incomplete (e.g. configuration.keyStoreID being null).

KeyManagerAPIInstantiationException - if the actual implementation cannot be instantiated.

getConfiguration

KeyManagerAPIConfiguration getConfiguration()

Get the current configuration of this KeyManagerAPI. If setConfiguration(KeyManagerAPIConfiguration) was not yet called, this is null.

Returns:

the KeyManagerAPIConfiguration (or null, if not yet configured).

initDateDependentKeyStrategy

DateDependentKeyStrategyInitResult initDateDependentKeyStrategy(DateDependentKeyStrategyInitParam param)
                                                                throws KeyStoreNotEmptyException,
                                                                       IOException

Initialise a new key-store with the DateDependentKeyStrategy.

Parameters:

param - the settings controlling the details of how to initialise it. Must not be null.

Returns:

Throws:

KeyStoreNotEmptyException

IOException

putUser

void putUser(String userName,
             char[] password)
             throws AuthenticationException,
                    IOException

Create a new user or change an existing user's password. If the password of the current user is modified, this instance of KeyManagerAPI will be updated with a new configuration, automatically. Other instances of KeyManagerAPI - even in the same JVM - are not updated, though.

Parameters:

userName - the name of the new user.

password - the password of the new user.

Throws:

AuthenticationException - if the authUserName or the authPassword is incorrect.

IOException - if the communication with the key-store (either local key-store-file or remote key-server) fails.

deleteUser

void deleteUser(String userName)
                throws AuthenticationException,
                       CannotDeleteLastUserException,
                       IOException

Delete a user. If the specified user does not exist, this method is a no-op. Note, that the current user can delete himself. In this case, a 2nd call to this method would cause an AuthenticationException.

Parameters:

userName - the name of the user to be deleted.

Throws:

AuthenticationException - if the authUserName or the authPassword is incorrect.

CannotDeleteLastUserException - if you attempted to delete the last user (which would render the key-store to be totally unreadable).

IOException - if the communication with the key-store (either local key-store-file or remote key-server) fails.

getCryptoSession

CryptoSession getCryptoSession(String appServerBaseURL)
                               throws AuthenticationException,
                                      IOException

Get a session for a certain application server.

Parameters:

appServerBaseURL - the base-url of the app-server-key-manager-channel (must not be null). 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".

Returns:

the session; never null.

Throws:

AuthenticationException - if the authUserName or the authPassword is incorrect.

IOException - if the communication with the key-store (either local key-store-file or remote key-server) fails.