org.eu.mayrhofer.authentication.relate
Class RelateAuthenticationProtocol

java.lang.Object
  org.eu.mayrhofer.authentication.AuthenticationEventSender
      org.eu.mayrhofer.authentication.DHOverTCPWithVerification
          org.eu.mayrhofer.authentication.relate.RelateAuthenticationProtocol

public class RelateAuthenticationProtocol
extends DHOverTCPWithVerification

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 an InetAddress 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 (InetAddress) represents the remote host 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 keepSocketConnected 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 TCP Socket object as its second entry when keepSocketConnected has been set to true. The authentication failure and progress events to not go to these lengths and will return either an InetAddress 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

Field Summary

static int

TcpPort

Fields inherited from class org.eu.mayrhofer.authentication.DHOverTCPWithVerification

useJSSE

Fields inherited from class org.eu.mayrhofer.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(java.net.InetAddress remote, java.lang.Object optionalRemoteId, java.lang.Exception e, java.lang.String message) Called by the base class when the whole authentication protocol failed.
protected void	protocolProgressHook(java.net.InetAddress remote, java.lang.Object optionalRemoteId, int cur, int max, java.lang.String message) Called by the base class when the whole authentication protocol shows progress.
protected void	protocolSucceededHook(java.net.InetAddress remote, java.lang.Object optionalRemoteId, java.lang.String optionalParameterFromRemote, byte[] sharedSessionKey, java.net.Socket toRemote) Called by the base class when the whole authentication protocol succeeded.
protected void	resetHook() 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	startVerification(byte[] sharedAuthenticationKey, java.net.InetAddress remote, java.lang.String param, java.net.Socket socketToRemote) Called by the base class when shared keys have been established and should be verified now.

Methods inherited from class org.eu.mayrhofer.authentication.DHOverTCPWithVerification

isIdle, isVerifying, startAuthentication, startServer, stopServer, verificationFailure, verificationSuccess

Methods inherited from class org.eu.mayrhofer.authentication.AuthenticationEventSender

addAuthenticationProgressHandler, raiseAuthenticationFailureEvent, raiseAuthenticationProgressEvent, raiseAuthenticationSuccessEvent, removeAuthenticationProgressHandler

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

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.eu.mayrhofer.authentication.AuthenticationProgressHandler), DongleProtocolHandler.handleDongleCommunication(byte[], byte[], int, org.eu.mayrhofer.authentication.InterlockProtocol, org.eu.mayrhofer.authentication.InterlockProtocol)

resetHook

protected void resetHook()

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

Specified by:

resetHook in class DHOverTCPWithVerification

protocolSucceededHook

protected void protocolSucceededHook(java.net.InetAddress remote,
                                     java.lang.Object optionalRemoteId,
                                     java.lang.String optionalParameterFromRemote,
                                     byte[] sharedSessionKey,
                                     java.net.Socket toRemote)

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 DHOverTCPWithVerification

Parameters:

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

optionalRemoteId - An optional remote ID, exactly as it has been passed to verificationSuccess. May be null.

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.

toRemote - If it has been requested that the socket to the remote host should stay connected, it will be passed in this parameter. May be null.

protocolFailedHook

protected void protocolFailedHook(java.net.InetAddress remote,
                                  java.lang.Object optionalRemoteId,
                                  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 DHOverTCPWithVerification

Parameters:

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

optionalRemoteId - An optional remote ID, exactly as it has been passed to verificationSuccess or verificationFailure. May be null.

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

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

protocolProgressHook

protected void protocolProgressHook(java.net.InetAddress remote,
                                    java.lang.Object optionalRemoteId,
                                    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 DHOverTCPWithVerification

Parameters:

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

optionalRemoteId - An optional remote ID, exactly as it has been passed to verificationSuccess or verificationFailure. May be null.

cur - @see AuthenticationProgressHandler#AuthenticationProgress

max - @see AuthenticationProgressHandler#AuthenticationProgress

message - @see AuthenticationProgressHandler#AuthenticationProgress

startVerification

protected void startVerification(byte[] sharedAuthenticationKey,
                                 java.net.InetAddress remote,
                                 java.lang.String param,
                                 java.net.Socket socketToRemote)

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:

startVerification in class DHOverTCPWithVerification

Parameters:

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

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

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

socketToRemote - This socket is still open and can be used to communicate with the remote host for verifying the authentication key. When it is used, care must be taken not to consume any bytes from the remote end that are not expected during verification, because the same channel will be used for exchanging status information about the success or failure of the whole authentication protocol.

setSimulationMode

public static void setSimulationMode(boolean simulation)

main

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

Throws:

java.lang.Exception