org.openuat.authentication
Class KeyManager

java.lang.Object
  org.openuat.authentication.AuthenticationEventSender
      org.openuat.authentication.KeyManager

public class KeyManager
extends AuthenticationEventSender

This class manages shared secret keys. It assumes that up to two keys are shared with a remote host, an authentication key and a session key for further secure communication. Remote hosts are identified by their RemoteConnection objects, which must implement proper equals() methods. Note that RemoteConnection objects are used primarily for identification purposes, but also for communication with the remote host. A caller may not assume that the RemoteConnection reference can be used to communicate at all times - the respective channel may have been closed. A remote host can, as far as this class is concerned, be in one of the following states:

• STATE_NONEXISTANT: This remote host is simply unknown and has not yet been involved in any key agreement with this KeyManager object.
• STATE_IDLE: The host is known, but key agreement has not yet been started. No keys are known at this time.
• STATE_KEY_AGREEMENT: The host is known, and a key agreement with it is currently running. No keys are known at this time.
• STATE_VERIFICATION: The host is known and two keys have already been agreed to. The keys are unauthenticated and can not yet be used for secure communication.
• STATE_SUCCEEDED: An authenticated secret shared (session) key is known for this host and can be used for secure communication. The authentication key has already been wiped from memory.
• STATE_FAILED: The host is known, but either key agreement or verification failed. No keys are known at this time, as they have already been wiped from memory.

When host references are removed or any error happens, key material is actively wiped from memory to prevent leaking secret keys. This class also extends AuthenticationEventSender and will forward all AuthenticationFailure and AuthenticationProgress events to all registered listeners. AuthenticationSuccess events are not forwarded, but instead the startVerification method of all registered KeyManagerEventHandler objects will be called after extracting the keys from the AuthenticationSuccess event.

Version:

1.0

Author:

Rene Mayrhofer

Nested Class Summary

static interface

KeyManager.VerificationHandler This interface must be implemented by classes used for key verification.

Field Summary

protected java.lang.String	instanceId This may be set to distinguish multiple instances running on the same machine.
static int	STATE_FAILED Possible state, indicates that the whole authentication protocol has failed.
static int	STATE_IDLE Possible state, indicates that the authentication has not been started yet.
static int	STATE_KEY_AGREEMENT Possible state, indicates that the host authentication is running.
static int	STATE_NONEXISTANT Possible state, indicates that nothing is known about this host.
static int	STATE_SUCCEEDED Possible state, indicates that the whole authentication protocol has been completed successfully.
static int	STATE_VERIFICATION Possible state, indicates that the key verification is running (and the key agreement has thus implicitly been completed successfully).

Fields inherited from class org.openuat.authentication.AuthenticationEventSender

eventsHandlers

Constructor Summary

KeyManager(boolean concurrentVerificationSupported, java.lang.String instanceId)
Initializes the key manager.

Method Summary

void	addVerificationHandler(KeyManager.VerificationHandler listener) Register a listener for verification events.
void	dispose() Wipes all key material by calling wipe().
boolean	fail(RemoteConnection host) Sets a remote host to STATE_FAILED.
byte[]	getAuthenticationKey(RemoteConnection host) Returns the authentication key for a remote host.
AuthenticationProgressHandler	getHostAuthenticationHandler() Returns an implementation of AuthenticationProgressHandler that should be registered with a HostProtocolHandler so that KeyManager will receive the keys that are agreed to.
RemoteConnection[]	getHostsInState(int state) This method returns all host reference for hosts that are in the requested state.
java.lang.Object	getOptionalRemoteReference(RemoteConnection host) Returns the optional remote reference for a remote host.
byte[]	getSessionKey(RemoteConnection host) Returns the session key for a remote host.
int	getState(RemoteConnection host) Returns the current state of a remote host.
boolean	isConcurrentVerificationSupported() Simply returns the value of concurrentVerificationSupported passed to the constructor.
boolean	isIdle() This method returns true if and only if no remote host is currently in states STATE_KEY_AGREEMENT, STATE_VERIFICATION, or STATE_FAILED.
boolean	removeVerificationHandler(KeyManager.VerificationHandler listener) De-register a listener for verification events.
boolean	reset(RemoteConnection host) Sets a remote host to STATE_IDLE.
void	setOptionalRemoteReference(RemoteConnection host, java.lang.Object optionalRemoteReference) Returns the optional remote reference for a remote host.
boolean	startKeyAgreement(RemoteConnection host) Sets a remote host to STATE_KEY_AGREEMENT.
boolean	succeed(RemoteConnection host) Sets a remote host to STATE_SUCCEEDED.
void	wipe() Wipes all key material by calling wipe() on each State object.

Methods inherited from class org.openuat.authentication.AuthenticationEventSender

addAuthenticationProgressHandler, raiseAuthenticationFailureEvent, raiseAuthenticationProgressEvent, raiseAuthenticationStartedEvent, raiseAuthenticationSuccessEvent, removeAuthenticationProgressHandler, setAuthenticationProgressHandlers

Methods inherited from class java.lang.Object

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

Field Detail

STATE_NONEXISTANT

public static final int STATE_NONEXISTANT

Possible state, indicates that nothing is known about this host.

See Also:

Constant Field Values

STATE_IDLE

public static final int STATE_IDLE

Possible state, indicates that the authentication has not been started yet.

See Also:

Constant Field Values

STATE_KEY_AGREEMENT

public static final int STATE_KEY_AGREEMENT

Possible state, indicates that the host authentication is running.

See Also:

Constant Field Values

STATE_VERIFICATION

public static final int STATE_VERIFICATION

Possible state, indicates that the key verification is running (and the key agreement has thus implicitly been completed successfully).

See Also:

Constant Field Values

STATE_SUCCEEDED

public static final int STATE_SUCCEEDED

Possible state, indicates that the whole authentication protocol has been completed successfully.

See Also:

Constant Field Values

STATE_FAILED

public static final int STATE_FAILED

Possible state, indicates that the whole authentication protocol has failed.

See Also:

Constant Field Values

instanceId

protected java.lang.String instanceId

This may be set to distinguish multiple instances running on the same machine.

Constructor Detail

KeyManager

public KeyManager(boolean concurrentVerificationSupported,
                  java.lang.String instanceId)

Initializes the key manager.

Parameters:

concurrentVerificationSupported - If set to false, then only one remote host can be in STATE_VERIFICATION at any time. This can be used when the sensor hardware used for key verification can only interact with one remote host at the same time.

instanceId - This parameter may be used to distinguish different instances of this class running on the same machine. It will be used in logging and error messages. May be set to null.

Method Detail

addVerificationHandler

public void addVerificationHandler(KeyManager.VerificationHandler listener)

Register a listener for verification events.

removeVerificationHandler

public boolean removeVerificationHandler(KeyManager.VerificationHandler listener)

De-register a listener for verification events.

getState

public int getState(RemoteConnection host)

Returns the current state of a remote host.

isConcurrentVerificationSupported

public boolean isConcurrentVerificationSupported()

Simply returns the value of concurrentVerificationSupported passed to the constructor.

getHostAuthenticationHandler

public AuthenticationProgressHandler getHostAuthenticationHandler()

Returns an implementation of AuthenticationProgressHandler that should be registered with a HostProtocolHandler so that KeyManager will receive the keys that are agreed to.

isIdle

public boolean isIdle()

This method returns true if and only if no remote host is currently in states STATE_KEY_AGREEMENT, STATE_VERIFICATION, or STATE_FAILED. It can be used to determine if start() can be called when concurrent verification is not supported. STATE_FAILED does not count as idle because this needs attention (and most probably resetting the failed host).

See Also:

concurrentVerificationSupported

getHostsInState

public RemoteConnection[] getHostsInState(int state)

This method returns all host reference for hosts that are in the requested state.

Parameters:

state - One of STATE_NONEXISTANT, STATE_IDLE, STATE_KEY_AGREEMENT, STATE_VERIFICATION, STATE_SUCCEEDED, STATE_FAILED.

Returns:

An array of all host reference that are currently in this state. It may be empty (length == 0), but not null.

Throws:

java.lang.IllegalArgumentException - if state < STATE_IDLE or state > STATE_FAILED.

succeed

public boolean succeed(RemoteConnection host)

Sets a remote host to STATE_SUCCEEDED. This is only possible if it has been in STATE_VERIFICATION at the time this method is called. When this check is passed, the method also wipes the authentication key, since after verification this is no longer needed (and should not be re-used).

Parameters:

host - The host to succeed.

Returns:

true if successful, false if the host is nonexistant or not in STATE_VERIFICATION.

startKeyAgreement

public boolean startKeyAgreement(RemoteConnection host)

Sets a remote host to STATE_KEY_AGREEMENT. This is only possible if it has been in STATE_IDLE at the time this method is called. The method should be called upon outgoing connections, while the state will be automatically updated to STATE_KEY_AGREEMENT for incoming connections. When the host reference is unknown when the method is called, it will be created.

Parameters:

host - The host to reset.

Returns:

true if successful, false if the host is nonexistant or not in STATE_IDLE.

fail

public boolean fail(RemoteConnection host)

Sets a remote host to STATE_FAILED. The method also wipes all key material that may be held for this host.

Parameters:

host - The host to fail.

Returns:

true if successful, false if the host is nonexistant.

reset

public boolean reset(RemoteConnection host)

Sets a remote host to STATE_IDLE. The method also wipes all key material that may be held for this host.

Parameters:

host - The host to reset.

Returns:

true if successful, false if the host is nonexistant.

getAuthenticationKey

public byte[] getAuthenticationKey(RemoteConnection host)

Returns the authentication key for a remote host. An authentication key will only exist if the host is in STATE_VERIFICATION.

Parameters:

host - The remote host to retrieve the authentication key for.

Returns:

The key if set or null if the host is nonexistant or not in STATE_VERIFICATION.

getSessionKey

public byte[] getSessionKey(RemoteConnection host)

Returns the session key for a remote host. A session key will only exist if the host is in STATE_SUCCEEDED.

Parameters:

host - The remote host to retrieve the session key for.

Returns:

The key if set or null if the host is nonexistant or not in STATE_SUCCEEDED.

getOptionalRemoteReference

public java.lang.Object getOptionalRemoteReference(RemoteConnection host)

Returns the optional remote reference for a remote host. This may hold an additional reference that key verification protocols need to keep track of their state.

Parameters:

host - The remote host to retrieve the optional remote reference.

Returns:

The reference if set or null if the host is nonexistant.

setOptionalRemoteReference

public void setOptionalRemoteReference(RemoteConnection host,
                                       java.lang.Object optionalRemoteReference)

Returns the optional remote reference for a remote host. This may hold an additional reference that key verification protocols need to keep track of their state.

Parameters:

host - The remote host to retrieve the optional remote reference.

dispose

public void dispose()

Wipes all key material by calling wipe().

wipe

public void wipe()

Wipes all key material by calling wipe() on each State object.