org.openuat.authentication.relate
Class RelateAuthenticationProtocol

java.lang.Object
  org.openuat.authentication.AuthenticationEventSender
      org.openuat.authentication.DHWithVerification
          org.openuat.authentication.relate.RelateAuthenticationProtocol

public class RelateAuthenticationProtocol
extends DHWithVerification

This is the main class of the relate authentication software: it ties together the host and dongle protocol handlers. Since both handlers work asynchronously in their own threads, this class must also handle the synchronisation between all events coming in from them. It can generate two types of events of its own: as a subclass of AuthenticationEventSender, it sende AuthenticationEvents to all registered AuthenticationProgressHandler. Additionally, when a ProgressEventHandler object is given to the constructor, it will generate the more specific relate events. The authentication success event generated by this protocol will return an object array consisting of a String object and an Integer object for the remote parameter and either a byte or an object array as the result parameter. For the remote parameter, the first object (String) represents the remote canonical host name address, while the second object (Integer) represents the remote Relate id. The result parameter will contain only the session key as a byte array when keepConnected has been set to false in the constructor, but will contain an Object array with the session key (again as a byte array) as its first entry and the RemoteConnection object as its second entry when keepConnected has been set to true. The authentication failure and progress events to not go to these lengths and will return either a String object or an Integer object as the remote parameter, depending on the current stage of the Relate protocol when the event occurs.

Version:

1.0

Author:

Rene Mayrhofer

Nested Class Summary

Nested classes/interfaces inherited from class org.openuat.authentication.DHWithVerification

DHWithVerification.HostAuthenticationEventHandler, DHWithVerification.StartVerificationHandler

Field Summary

static int	KeyAgreementProtocolTimeout Allow the (incoming) key agreement to take at maximum this amout of ms.
static int	TcpPort

Fields inherited from class org.openuat.authentication.DHWithVerification

instanceId, keyManager, server, useJSSE

Fields inherited from class org.openuat.authentication.AuthenticationEventSender

eventsHandlers

Constructor Summary

RelateAuthenticationProtocol(java.lang.String serialPort, uk.ac.lancs.relate.core.MeasurementManager manager, boolean useJSSE, boolean keepSocketConnected, uk.ac.lancs.relate.auth.ProgressEventHandler relateEventHandler)
Initialized the authentication object with the contact data of the remote device to authenticate with.

Method Summary

static void	main(java.lang.String[] args)
protected void	protocolFailedHook(boolean failHard, RemoteConnection remote, java.lang.Object optionalVerificationId, java.lang.Exception e, java.lang.String message) Called by the base class when the whole authentication protocol failed.
protected void	protocolProgressHook(RemoteConnection remote, int cur, int max, java.lang.String message) Called by the base class when the whole authentication protocol shows progress.
protected void	protocolStartedHook(RemoteConnection remote) This hook will be called when the whole authentication protocol has been started.
protected void	protocolSucceededHook(RemoteConnection remote, java.lang.Object optionalVerificationId, java.lang.String optionalParameterFromRemote, byte[] sharedSessionKey) Called by the base class when the whole authentication protocol succeeded.
protected void	resetHook(RemoteConnection remote) Called by the base class when the object is reset to idle state.
static void	setSimulationMode(boolean simulation)
boolean	startAuthentication(java.lang.String remoteHost, int remoteRelateId, int rounds) Starts the spatial authentication protocol in the background.
protected void	startVerificationAsync(byte[] sharedAuthenticationKey, java.lang.String param, RemoteConnection toRemote) Called by the base class when shared keys have been established and should be verified now.

Methods inherited from class org.openuat.authentication.DHWithVerification

authenticationFailed, isIdle, reset, startAuthentication, startListening, stopListening, verificationFailure, verificationSuccess

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

TcpPort

public static final int TcpPort

See Also:

Constant Field Values

KeyAgreementProtocolTimeout

public static final int KeyAgreementProtocolTimeout

Allow the (incoming) key agreement to take at maximum this amout of ms.

See Also:

Constant Field Values

Constructor Detail

RelateAuthenticationProtocol

public RelateAuthenticationProtocol(java.lang.String serialPort,
                                    uk.ac.lancs.relate.core.MeasurementManager manager,
                                    boolean useJSSE,
                                    boolean keepSocketConnected,
                                    uk.ac.lancs.relate.auth.ProgressEventHandler relateEventHandler)

Initialized the authentication object with the contact data of the remote device to authenticate with. This constructor also gets a reference measurement to the remote relate id by itself. This needs better integration with the Relate framework, the reference measurement should come from "the outside".

Parameters:

serialPort - The serial port to which the dongle is connected

manager - The measurement manager to use. This manager should be registered at the dongle that is connected to serialPort and should keep a history of the last measurement received locally from this dongle. It will be used by RelateAuthenticationProtocol to fetch the reference measurement before starting the spatial authentication protocol.

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.

keepSocketConnected - If set to true, the opened client socket soc 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. The socket will always be closed on authentication failures. If in doubt, set to false;

relateEventHandler - If set to an object != null, it will get notified of all events.

Method Detail

startAuthentication

public boolean startAuthentication(java.lang.String remoteHost,
                                   int remoteRelateId,
                                   int rounds)
                            throws java.net.UnknownHostException,
                                   java.io.IOException

Starts the spatial authentication protocol in the background. Listeners should subscribe to authentication events to get notified about the progress of authentication.

Parameters:

remoteHost - The hostname/IP address of the remote device to send an authentication request to.

remoteRelateId - The relate id of the remote device. This is set by the client only to enable stricter error checks. T

rounds - The number of rounds that should be used for the dongle authentication. This directly influences the achieved security level, as described in DongleProtocolHandler#handleDongleCommunication.

Returns:

true if the authentication could be started, false otherwise.

Throws:

java.net.UnknownHostException

java.io.IOException

See Also:

AuthenticationEventSender.addAuthenticationProgressHandler(org.openuat.authentication.AuthenticationProgressHandler), DongleProtocolHandler.handleDongleCommunication(byte[], byte[], org.openuat.authentication.InterlockProtocol, org.openuat.authentication.InterlockProtocol)

resetHook

protected void resetHook(RemoteConnection remote)

Called by the base class when the object is reset to idle state.

Specified by:

resetHook in class DHWithVerification

protocolSucceededHook

protected void protocolSucceededHook(RemoteConnection remote,
                                     java.lang.Object optionalVerificationId,
                                     java.lang.String optionalParameterFromRemote,
                                     byte[] sharedSessionKey)

Called by the base class when the whole authentication protocol succeeded. Note: The optionalRemoteId object is (ab)used not to pass an Integer object with the remote relate ID, but the full DongleProtocolHandler, so that the protocol execution times can be queried.

Specified by:

protocolSucceededHook in class DHWithVerification

Parameters:

remote - The remote host with which the key exchange succeeded. If it has not been requested that the connection should stay open (keepConnectedOnSuccess==true), then this will be closed immediately after the hook method returns.

optionalVerificationId - If the key verification step yielded any ID or reference that can be referred to, then this will be set. It is directly forwarded through from the call to verificationSuccess.

optionalParameterFromRemote - If the remote device reported an additional parameter with its success message, it will be put into this parameter. May be null.

sharedSessionKey - The shared session key (which is different from the shared authentication key used for verification) that can now be used for subsequent secure communication.

protocolFailedHook

protected void protocolFailedHook(boolean failHard,
                                  RemoteConnection remote,
                                  java.lang.Object optionalVerificationId,
                                  java.lang.Exception e,
                                  java.lang.String message)

Called by the base class when the whole authentication protocol failed. Note: The optionalRemoteId object may be (ab)used not to pass an Integer object with the remote relate ID, but the full DongleProtocolHandler, so that the protocol execution times can be queried. But since this method can also be called when HostAuthenticationProtocol fails, we don't know if optionalRemoteId is going to be set - can't use it here at all.

Specified by:

protocolFailedHook in class DHWithVerification

Parameters:

failHard - If true, then the protocol has failed hard, meaning that there can be no retry without another key agreement protocol run. Key material will be wiped after this hook returns. If false, only a soft failure occurred, meaning that the connection will be closed, but key material will not be wiped yet. Retrying key verification (i.e. authenticating the key agreement) will be possible.

remote - The remote host with which the key exchange failed. If it has not been requested that the connection should stay open (keepConnectedOnFailure==true), then this will be closed immediately after the hook method returns.

optionalVerificationId - If the key verification step yielded any ID or reference that can be referred to, then this will be set. It is directly forwarded through from the call to verificationSuccess or verificationFailed. If the protocol already failed during key agreement (or the derived class did not set the parameter), then this will be null.

e - If not null, the exception describing the failure.

message - If not null, the message describing the failure.

protocolProgressHook

protected void protocolProgressHook(RemoteConnection remote,
                                    int cur,
                                    int max,
                                    java.lang.String message)

Called by the base class when the whole authentication protocol shows progress. Note: The optionalRemoteId object may be (ab)used not to pass an Integer object with the remote relate ID, but the full DongleProtocolHandler, so that the protocol execution times can be queried. But since this method can also be called when HostAuthenticationProtocol fails, we don't know if optionalRemoteId is going to be set - can't use it here at all.

Specified by:

protocolProgressHook in class DHWithVerification

Parameters:

remote - The remote host with which the key exchange progressed.

cur - @see AuthenticationProgressHandler#AuthenticationProgress

max - @see AuthenticationProgressHandler#AuthenticationProgress

message - @see AuthenticationProgressHandler#AuthenticationProgress

protocolStartedHook

protected void protocolStartedHook(RemoteConnection remote)

Description copied from class: DHWithVerification

This hook will be called when the whole authentication protocol has been started. Derived classes should implement it to react to this progress.

Specified by:

protocolStartedHook in class DHWithVerification

Parameters:

remote - The remote host with which the key exchange started.

startVerificationAsync

protected void startVerificationAsync(byte[] sharedAuthenticationKey,
                                      java.lang.String param,
                                      RemoteConnection toRemote)

Called by the base class when shared keys have been established and should be verified now. In this implementation, verification is done by starting a DongleAuthenticationProtocol.

Specified by:

startVerificationAsync in class DHWithVerification

Parameters:

sharedAuthenticationKey - This key should be verified to be equal on both sides.

param - Optional parameters sent by the remote host during the key agreement phase.

setSimulationMode

public static void setSimulationMode(boolean simulation)

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Throws:

java.lang.Exception