org.openuat.util
Class HostServerBase

java.lang.Object
  org.openuat.authentication.AuthenticationEventSender
      org.openuat.util.HostServerBase

All Implemented Interfaces:

java.lang.Runnable, HostAuthenticationServer

Direct Known Subclasses:

BluetoothRFCOMMServer, TCPPortServer

public abstract class HostServerBase
extends AuthenticationEventSender
implements HostAuthenticationServer, java.lang.Runnable

This is a base class for listening to connections and spawning HostProtocolHandler objects upon incoming connections. It takes care of handling the background listening thread.

Version:

1.1, changes to 1.0: this is now a base class for TCP and RFCOMM implementations, and startListening can now throw an IOException

Author:

Rene Mayrhofer

Field Summary

protected boolean	keepConnected If set to true, the fully connected socket/channel that represents a connection to a client will not be closed as soon as the HostProtocolHandler is finished with it, but will be passed to the authentication success event of the respective listener for further reuse.
protected SimpleKeyAgreement	permanentKeyAgreementInstance If set, this will be passed on to the constructed HostProtocolHandler objects.
protected byte[]	preAuthenticationMessageFromClient If this is set, then we have received a (long) pre-authentication message from the client and will use it to verify its public key.
protected java.util.Vector	presharedShortSecrets If this is set, then we have some form of user input that has been created _before_ starting a specific protocol instance and is assumed to be secret.
protected java.util.Hashtable	protocolCommandHandlers This only keeps the command handlers so that they can be pre-registered and then be passed onto HostProtocolHandler objects when they are instantiated.
protected int	protocolTimeoutMs If =!
protected boolean	running Used to signal the listening thread to stop itself.
protected boolean	useJSSE If set to true, the JSSE will be used, if set to false, the Bouncycastle Lightweight API.

Fields inherited from class org.openuat.authentication.AuthenticationEventSender

eventsHandlers

Constructor Summary

HostServerBase(boolean keepConnected, boolean useJSSE, int protocolTimeoutMs)
Initializes the listener.

Method Summary

void	addProtocolCommandHandler(java.lang.String command, ProtocolCommandHandler handler) Adds a protocol command handler.
SimpleKeyAgreement	getPermanentKeyAgreementInstance() Returns the permanent key agreement instance.
byte[]	getPermanentPreAuthenticationMessage()
byte[]	getPreAuthenticationMessageFromClient() Returns the pre-authentication message received from the client.
java.util.Vector	getPresharedShortSecrets() Returns the user-input preshared short secret.
boolean	isRunning() Returns true if the server is running, false otherwise.
boolean	removeProtocolCommandHandler(java.lang.String command) Removes a protocol command handler.
void	setPermanentKeyAgreementInstance(SimpleKeyAgreement keyAgreement) Sets the permanent key agreement instance to use for all subsequent HostProtocolHandler invocations.
void	setPreAuthenticationMessageFromClient(byte[] publicKeyCommitment) Sets a pre-authentication message received from the client and committing it to its public key that it will use when starting the proper protocol run.
void	setPresharedShortSecret(byte[] presharedShortSecret) Sets a preshared short secret as entered by the user.
void	setPresharedShortSecrets(java.util.Vector presharedShortSecrets) Sets a list of preshared short secrets as entered by the user.
boolean	setProtocolCommandHandler(java.util.Hashtable handlers)
void	start() Starts a background thread (using the run() method of this class) that will listen for incoming connections.
protected void	startProtocol(RemoteConnection remote) This is a small helper function that derived classes should call after accepting an incoming connection.
void	stop() Signals the background listening thread to stop and waits for it.

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

Methods inherited from interface org.openuat.util.HostAuthenticationServer

addAuthenticationProgressHandler, removeAuthenticationProgressHandler

Methods inherited from interface java.lang.Runnable

run

Field Detail

running

protected boolean running

Used to signal the listening thread to stop itself.

keepConnected

protected boolean keepConnected

If set to true, the fully connected socket/channel that represents a connection to a client will not be closed as soon as the HostProtocolHandler is finished with it, but will be passed to the authentication success event of the respective listener for further reuse.

useJSSE

protected boolean useJSSE

If set to true, the JSSE will be used, if set to false, the Bouncycastle Lightweight API.

protocolTimeoutMs

protected int protocolTimeoutMs

If =! 1, specifies a timeout for the (incoming) protocol runs started in the background.

presharedShortSecrets

protected java.util.Vector presharedShortSecrets

If this is set, then we have some form of user input that has been created _before_ starting a specific protocol instance and is assumed to be secret. This Vector may contain multiple entries, in this case each entry is assumed to be a 'candidate secret'.
Note: all entries have to be of the same length!

preAuthenticationMessageFromClient

protected byte[] preAuthenticationMessageFromClient

If this is set, then we have received a (long) pre-authentication message from the client and will use it to verify its public key. This must be set before the client connects to us (and thus before the HostProtocolHandler instance gets created) to have any effect.

permanentKeyAgreementInstance

protected SimpleKeyAgreement permanentKeyAgreementInstance

If set, this will be passed on to the constructed HostProtocolHandler objects.

protocolCommandHandlers

protected java.util.Hashtable protocolCommandHandlers

This only keeps the command handlers so that they can be pre-registered and then be passed onto HostProtocolHandler objects when they are instantiated.

Constructor Detail

HostServerBase

public HostServerBase(boolean keepConnected,
                      boolean useJSSE,
                      int protocolTimeoutMs)

Initializes the listener.

Parameters:

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.

protocolTimeoutMs - 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.

See Also:

If set to true, the connection to the client will be kept connected after the registered HostProtocolHandler has finished. This allows the socket to be reused for additional communication after the first authentication protocol has been completed.

Method Detail

addProtocolCommandHandler

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

Description copied from interface: HostAuthenticationServer

Adds a protocol command handler.

Specified by:

addProtocolCommandHandler in interface HostAuthenticationServer

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.

See Also:

HostProtocolHandler.addProtocolCommandHandler(java.lang.String, org.openuat.util.ProtocolCommandHandler)

removeProtocolCommandHandler

public boolean removeProtocolCommandHandler(java.lang.String command)

Description copied from interface: HostAuthenticationServer

Removes a protocol command handler.

Specified by:

removeProtocolCommandHandler in interface HostAuthenticationServer

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).

See Also:

HostProtocolHandler.removeProtocolCommandHandler(java.lang.String)

setProtocolCommandHandler

public boolean setProtocolCommandHandler(java.util.Hashtable handlers)

See Also:

HostProtocolHandler.setProtocolCommandHandlers(java.util.Hashtable)

setPresharedShortSecret

public void setPresharedShortSecret(byte[] presharedShortSecret)

Sets a preshared short secret as entered by the user. This must remain secret until the protocol finished and must not be re-used again for another protocol run!

setPresharedShortSecrets

public void setPresharedShortSecrets(java.util.Vector presharedShortSecrets)

Sets a list of preshared short secrets as entered by the user. Each entry represents a 'candidate secret'. This must remain secret until the protocol finished and must not be re-used again for another protocol run!

getPresharedShortSecrets

public java.util.Vector getPresharedShortSecrets()

Returns the user-input preshared short secret. May be null when not used.

setPreAuthenticationMessageFromClient

public void setPreAuthenticationMessageFromClient(byte[] publicKeyCommitment)

Sets a pre-authentication message received from the client and committing it to its public key that it will use when starting the proper protocol run. This must be set before the client connects to us (and thus before the HostProtocolHandler instance gets created) to have any effect.

getPreAuthenticationMessageFromClient

public byte[] getPreAuthenticationMessageFromClient()

Returns the pre-authentication message received from the client. May be null when not used.

setPermanentKeyAgreementInstance

public void setPermanentKeyAgreementInstance(SimpleKeyAgreement keyAgreement)

Sets the permanent key agreement instance to use for all subsequent HostProtocolHandler invocations. This should be used with care and only if ephemeral Diffie-Hellman keys can not be supported. The only real use case at the time of this writing is pre-authentication with long public key commitments when those need to be static (e.g. printed on the case of a device).

getPermanentKeyAgreementInstance

public SimpleKeyAgreement getPermanentKeyAgreementInstance()

Returns the permanent key agreement instance. May be null when not used.

getPermanentPreAuthenticationMessage

public byte[] getPermanentPreAuthenticationMessage()

start

public void start()
           throws java.io.IOException

Starts a background thread (using the run() method of this class) that will listen for incoming connections.

Specified by:

start in interface HostAuthenticationServer

Throws:

java.io.IOException

stop

public void stop()
          throws InternalApplicationException

Signals the background listening thread to stop and waits for it. This method will not return until the listening thread has terminated.

Specified by:

stop in interface HostAuthenticationServer

Throws:

InternalApplicationException

isRunning

public boolean isRunning()

Returns true if the server is running, false otherwise.

startProtocol

protected void startProtocol(RemoteConnection remote)

This is a small helper function that derived classes should call after accepting an incoming connection. It fires off a HostProtocolHandler in the background and registers all listeners beforehand.

Parameters:

remote - The (already opened) remote connection to use.