org.openuat.authentication
Class HostProtocolHandler

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

public class HostProtocolHandler
extends AuthenticationEventSender

This class handles the key agreement protocol between two hosts on a stream level. It implements both sides of the protocol, allowing to handle incoming connections (i.e. incoming authentication requests) as well as initiating outgoing connections (i.e. outgoing authentication requests). Events are raised upon authentication success, failure and during the progress of an authentication protocol. The authentication success event generated by this protocol will return a RemoteConnection object for the remote parameter and an Object array as the result parameter. This object array will always have at least 3 objects: two byte arrays representing the session key and the authentication key and a String representing the optional parameter that might have been specified by the client or which might have been passed to the protocol when in client mode. This third object in the object array can be null if no parameter was specified, but it will always be there. An optional fourth object will be included with the array when the keepSocketConnected flag was set. This fourth paramater will then contain the still connected channel object. If, in addition to a simple Diffie-Hellman based key agreement, the server part of this HostProtocolHandler should support other commands, then custom handlers can be registered with addProtocolCommandHandlers. These commands can subsequently be handled at the stage when the Protocol_AuthenticationRequest command would be expected.

Version:

1.1, changes to 1.0: Support registering additional protocol handlers that are called for their registered protocol.

Author:

Rene Mayrhofer

Field Summary

static int	AuthenticationStages At the moment, the whole protocol consists of 4 stages.
static java.lang.String	Protocol_AuthenticationAcknowledge
static java.lang.String	Protocol_AuthenticationRequest
static java.lang.String	Protocol_AuthenticationRequest_Param This is an optional field in the authentication request line, where the client can pass parameters to the next authentication protocol.
static java.lang.String	Protocol_Hello These are the messages of the ASCII authentication protocol.

Fields inherited from class org.openuat.authentication.AuthenticationEventSender

eventsHandlers

Constructor Summary

HostProtocolHandler(RemoteConnection con, int timeoutMs, boolean keepConnected, boolean useJSSE)
This class should only be instantiated by HostServerSocket for incoming connections or with the static startAuthenticatingWith method for outgoing connections.

Method Summary

void	addProtocolCommandHandler(java.lang.String command, ProtocolCommandHandler handler) Adds a protocol command handler.
boolean	removeProtocolCommandHandler(java.lang.String command) Removes a protocol command handler.
void	setProtocolCommandHandlers(java.util.Hashtable handlers) Set the list of registered protocol command handlers, if none has been registered so far.
static void	startAuthenticationWith(RemoteConnection remote, AuthenticationProgressHandler eventHandler, int timeoutMs, boolean keepConnected, java.lang.String optionalParameter, boolean useJSSE) Outgoing authentication connections are done asynchronously just like the incoming connections.
void	startIncomingAuthenticationThread(boolean asynchronousCall) Starts a background thread for handling an incoming authentication request.

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

Protocol_Hello

public static final java.lang.String Protocol_Hello

These are the messages of the ASCII authentication protocol.

See Also:

Constant Field Values

Protocol_AuthenticationRequest

public static final java.lang.String Protocol_AuthenticationRequest

See Also:

Protocol_Hello, Constant Field Values

Protocol_AuthenticationRequest_Param

public static final java.lang.String Protocol_AuthenticationRequest_Param

This is an optional field in the authentication request line, where the client can pass parameters to the next authentication protocol.

See Also:

Protocol_AuthenticationRequest, Constant Field Values

Protocol_AuthenticationAcknowledge

public static final java.lang.String Protocol_AuthenticationAcknowledge

See Also:

Protocol_Hello, Constant Field Values

AuthenticationStages

public static final int AuthenticationStages

At the moment, the whole protocol consists of 4 stages.

See Also:

Constant Field Values

Constructor Detail

HostProtocolHandler

public HostProtocolHandler(RemoteConnection con,
                           int timeoutMs,
                           boolean keepConnected,
                           boolean useJSSE)

This class should only be instantiated by HostServerSocket for incoming connections or with the static startAuthenticatingWith method for outgoing connections.

Parameters:

con - The RemoteConnection to use for communication. It must already be connected to the other side, but will be shut down and closed before the protocol handler methods return, depending on the parameter keepConnected. The reason for this asymmetry (the connection must be connected by the caller, but is closed by the methods of this class) lies in the asynchronity: the protocol handler methods are called in background threads and must therefore dispose the objects before exiting.

timeoutMs - The maximum duration in milliseconds that this authentication protocol may take before it will abort with an AuthenticationFailed exception. Set to -1 to disable the timeout.

keepConnected - If set to true, the opened connection con is passed to the authentication success event (in the results parameter) for further re-use of the connection (e.g. passing additional information about further protocol steps). If set to false, the socket will be closed when this protocol is done with it.

useJSSE - If set to true, the JSSE API with the default JCE provider of the JVM will be used for cryptographic operations. If set to false, an internal copy of the Bouncycastle Lightweight API classes will be used.

Method Detail

addProtocolCommandHandler

public void addProtocolCommandHandler(java.lang.String command,
                                      ProtocolCommandHandler handler)

Adds a protocol command handler.

Parameters:

command - The command to react to.

handler - The handler that will be called to handle the protocol session when it is started with command.

removeProtocolCommandHandler

public boolean removeProtocolCommandHandler(java.lang.String command)

Removes a protocol command handler.

Parameters:

command - The command to stop reacting to.

Returns:

true if the command handler was removed, false otherwise (if no handler was previously registered for this command).

setProtocolCommandHandlers

public void setProtocolCommandHandlers(java.util.Hashtable handlers)

Set the list of registered protocol command handlers, if none has been registered so far. This should only be used for initialization and will not do anything if any listener has been registered before.

Parameters:

handlers - The list of command handlers to use. Keys must be of type String, while values must be of type ProtocolCommandHandler.

startIncomingAuthenticationThread

public void startIncomingAuthenticationThread(boolean asynchronousCall)

Starts a background thread for handling an incoming authentication request. Should only be called by HostServerSocket after accepting a new connection.

Parameters:

asynchronousCall - When set to true, this method will perform the protocol asynchronously an return immediately to the caller (firing events later on from the other thread). When set to false, this method will block until the authentication protocol has been completed (events will be fired from within the thread of the caller)

startAuthenticationWith

public static void startAuthenticationWith(RemoteConnection remote,
                                           AuthenticationProgressHandler eventHandler,
                                           int timeoutMs,
                                           boolean keepConnected,
                                           java.lang.String optionalParameter,
                                           boolean useJSSE)
                                    throws java.io.IOException

Outgoing authentication connections are done asynchronously just like the incoming connections. This method starts a new thread that tries to authenticate with the host given as remote. Callers need to subscribe to the Authentication* events to get notifications of authentication success, failure and progress.

Parameters:

remote - The remote connection to use for key agreement.

eventHandler - The event handler that should be notified of authentication events. Can be null (in which case no events are sent). If not null, it will be registered with a new HostProtocolHandler object before starting the authentication protocol so that it is guaranteed that all events are posted to the event handler.

timeoutMs - The maximum duration in milliseconds that this authentication protocol may take before it will abort with an AuthenticationFailed exception. Set to -1 to disable the timeout.

keepConnected - When set to true, the connection created in this method is not closed but passed to the authentation success event for further reuse.

optionalParameter - If not null, this string will be passed to the server in the authentication request message. Both the server and the client will then subsequently forward this string in their authentication success message. This parameter must be encoded in 7-bit ASCII and must not contain spaces.

useJSSE - If set to true, the JSSE API with the default JCE provider of the JVM will be used for cryptographic operations. If set to false, an internal copy of the Bouncycastle Lightweight API classes will be used.

Throws:

java.io.IOException