001 package org.cumulus4j.keymanager.api;
002
003 import java.io.IOException;
004
005 /**
006 * <p>
007 * Entry point for the key management API.
008 * </p><p>
009 * Use <code>new DefaultKeyManagerAPI()</code> to get an instance, which you should keep (e.g. in a static shared
010 * instance or some other context). Except for this one reference to {@link DefaultKeyManagerAPI} (i.e. an implementation class),
011 * you should only reference the interfaces of this API project!
012 * </p><p>
013 * An application server using Cumulus4j is only able to read or write data, when the key manager grants access to
014 * keys. In order to control this access, crypto-sessions are used (not to be confused with a servlet's session):
015 * An application server can only request a key from a key manager, when the crypto-session exists and is unlocked.
016 * Usually, a client will first unlock the session, then send a request to the app server and when the app server responded,
017 * lock the session, again. Thus most of the time, a key manager will reject access to keys, even while a connection
018 * between app server and key manager exists.
019 * </p><p>
020 * This entire API (all classes in <code>org.cumulus4j.keymanager.api</code>) is thread-safe. You can - and should - share
021 * one <code>KeyManagerAPI</code> instance across multiple threads.
022 * </p><p>
023 * Note, that you must {@link #setConfiguration(KeyManagerAPIConfiguration) configure} the <code>KeyManagerAPI</code>, before
024 * you can use it.
025 * </p>
026 *
027 * @author Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de
028 */
029 public interface KeyManagerAPI
030 {
031 /**
032 * <p>
033 * Set the configuration for this {@link KeyManagerAPI} instance.
034 * </p>
035 * <p>
036 * Before a KeyManagerAPI instance can actually be used, it first needs to be configured. The configuration
037 * passed to this method will be {@link KeyManagerAPIConfiguration#markReadOnly() marked read-only}.
038 * </p>
039 * @param configuration the configuration (which will be {@link KeyManagerAPIConfiguration#markReadOnly() marked read-only}
040 * by this operation). Must not be <code>null</code>.
041 * @throws IllegalArgumentException if the configuration is <code>null</code> or incomplete (e.g. {@link KeyManagerAPIConfiguration#getKeyStoreID() configuration.keyStoreID} being <code>null</code>).
042 * @throws KeyManagerAPIInstantiationException if the actual implementation cannot be instantiated.
043 */
044 void setConfiguration(KeyManagerAPIConfiguration configuration) throws IllegalArgumentException, KeyManagerAPIInstantiationException;
045
046 /**
047 * Get the current configuration of this {@link KeyManagerAPI}. If {@link #setConfiguration(KeyManagerAPIConfiguration)} was not
048 * yet called, this is <code>null</code>.
049 * @return the {@link KeyManagerAPIConfiguration} (or <code>null</code>, if not yet configured).
050 */
051 KeyManagerAPIConfiguration getConfiguration();
052
053 /**
054 * Initialise a new key-store with the {@link org.cumulus4j.keystore.DateDependentKeyStrategy}.
055 * @param param the settings controlling the details of how to initialise it. Must not be <code>null</code>.
056 * @return
057 * @throws KeyStoreNotEmptyException
058 * @throws IOException
059 */
060 DateDependentKeyStrategyInitResult initDateDependentKeyStrategy(DateDependentKeyStrategyInitParam param) throws KeyStoreNotEmptyException, IOException;
061
062 /**
063 * Create a new user or change an existing user's password. If the password of the {@link KeyManagerAPIConfiguration#getAuthUserName() current user}
064 * is modified, this instance of KeyManagerAPI will be updated with a new configuration, automatically. Other instances of <code>KeyManagerAPI</code>
065 * - even in the same JVM - are not updated, though.
066 * @param userName the name of the new user.
067 * @param password the password of the new user.
068 * @throws AuthenticationException if the {@link KeyManagerAPIConfiguration#setAuthUserName(String) authUserName} or the {@link KeyManagerAPIConfiguration#setAuthPassword(char[]) authPassword} is incorrect.
069 * @throws IOException if the communication with the key-store (either local key-store-file or remote key-server) fails.
070 */
071 void putUser(String userName, char[] password)
072 throws AuthenticationException, IOException;
073
074 /**
075 * Delete a user. If the specified user does not exist, this method is a no-op. Note, that the current user can delete himself.
076 * In this case, a 2nd call to this method would cause an <code>AuthenticationException</code>.
077 * @param userName the name of the user to be deleted.
078 * @throws AuthenticationException if the {@link KeyManagerAPIConfiguration#setAuthUserName(String) authUserName} or the {@link KeyManagerAPIConfiguration#setAuthPassword(char[]) authPassword} is incorrect.
079 * @throws CannotDeleteLastUserException if you attempted to delete the last user (which would render the key-store to be totally
080 * unreadable).
081 * @throws IOException if the communication with the key-store (either local key-store-file or remote key-server) fails.
082 */
083 void deleteUser(String userName)
084 throws AuthenticationException, CannotDeleteLastUserException, IOException;
085
086 /**
087 * <p>
088 * Get a session for a certain application server.
089 * </p>
090 *
091 * @param appServerBaseURL the base-url of the app-server-key-manager-channel (must not be <code>null</code>). This is the part of the URL before the "/KeyManagerChannel" -
092 * e.g. if the REST URL of the KeyManagerChannel-service is
093 * "https://serverUsingCumulus4j.mydomain.org/org.cumulus4j.keymanager.back.webapp/KeyManagerChannel", then this must be
094 * "https://serverUsingCumulus4j.mydomain.org/org.cumulus4j.keymanager.back.webapp".
095 * @return the session; never <code>null</code>.
096 * @throws AuthenticationException if the {@link KeyManagerAPIConfiguration#setAuthUserName(String) authUserName} or the {@link KeyManagerAPIConfiguration#setAuthPassword(char[]) authPassword} is incorrect.
097 * @throws IOException if the communication with the key-store (either local key-store-file or remote key-server) fails.
098 */
099 CryptoSession getCryptoSession(String appServerBaseURL) throws AuthenticationException, IOException;
100
101 }