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 protocol is called UACAP (unified auxiliary channel authentication protocol) and is based on the MANA IV family of multi-channel authentication protocols as specified in [Sven Laur and Kaisa Nyberg: "Efficient Mutual Data Authentication Using Manually Authenticated Strings: Extended Version"], specifically the MA-DH variant. However, it additionally implements an optional commitment-based exchange instead of just producing an out-of-band message from the key material for the input type authentication as explained below. This optional exchange is based on the MANA III protocol presented earlier and a variant proposed by Wong and Stajano.
This class has a dual interface and can thus be used in two different ways: either by driving the steps in the protocol from an outside caller on the instantiated object (henceforth referred to as the PlainObject style) or by registering an out-of-band channel that is subsequently used by HostProtocolHandler to handle the complete protocol run (henceforth referred to as the Hollywood style, cf. http://c2.com/cgi/wiki?HollywoodPrinciple). The PlainObject style is more flexible, as all steps "outside" the basic crypto protocol can be handled in any way, and is used by instantiating the object with the "basic" constructor. The Hollywood style can be easier to use, making the whole authentication protocol a black box by reducing it to a single method call, and can be used when an object implementing the OOBChannel interface is conveniently available. In this case, instantiate the object by passing the AuxiliaryChannel object to the constructor. In both cases, the object will fire usual authentication events for any outside listener.
TODO: This explanation needs to be updated to actually be true... The simplest possible case to use the ManaIV class for authentication is to instantiate it, Hollywood style, with an existing OOBChannel object and to let it run the key agreement:

 ManaIV m = new ManaIV(myOobChannel, true);
 m.addAuthenticationProgressHandler(myself);
 m.authenticate(); // this method returns immediately
 // ... wait for AuthenticationSuccess event and use the embedded key 
 

Alternatively, it may e.g. be used for the heavy crypto lifting, but out-of-band message transfer is handled in a custom way, PlainObject style: ManaIV m1 = new ManaIV(true); byte[] msg = m1.getOobMessage(); // transfer msg to the remote side in a secure way // on the other side: m2.addOobMessage(msg); 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 out-of-band message for transfer or comparison verification, 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. For input type authentication, the second object (the out-of-band message) will be null because authentication will have already happened at this stage. For the other two types, the first object (the session key) may only be used after successful (mutual) verification of the out-of-band message. An optional fourth object will be included with the array when the keepSocketConnected flag was set. This fourth parameter will then contain the still connected channel object.
If, in addition to UACAP, 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. TODO: signal to event listeners if the other side has been human-verified (in case of unidirectional OOB channels) TODO: rename out-of-band to auxiliary channel

Version:

2.0, changes to 1.0: The performProtocol method has been significantly improved and is now based upon a generalized MA-DH protocol (which includes at least one additional commitment message but may add more) instead of simple and potentially (depending on future uses of this class) insecure Diffie-Hellman-only key exchange., 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 5 stages.
protected RemoteConnection	connection The (already opened) connection used to communicate with the remote end, for both incoming and outgoing connections.
protected boolean	dontWipeKeyAgreement If ephemeral Diffie-Hellman keys should not be used (for example, because this host must use permanent keys because its pre-authentication commitment is on a printed sticker that can't be changed), then this can be set to true.
protected java.io.InputStream	fromRemote The stream to receive messages from the remote end.
protected boolean	keepConnected If set to false, connection will be closed after the protocol finished successfully.
protected SimpleKeyAgreement	keyAgreement This holds the single instance of our (Diffie-Hellman) based key agreement protocol.
protected byte[]	myPublicKey As soon as keyAgreement is initialized, this will also be set to our public key.
protected java.lang.String	optionalParameter An optional parameter that can be passed from the client to the server in its authentication request message.
protected java.util.Vector	presharedShortSecrets If this is set, then we have some form of user input that has been created _before_ starting the protocol instance and is assumed to be secret.
static java.lang.String	Protocol_AuthenticationAcknowledge
static java.lang.String	Protocol_AuthenticationAcknowledge2
static java.lang.String	Protocol_AuthenticationInputCommit
static java.lang.String	Protocol_AuthenticationInputOpen
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.
static java.lang.String	ProtocolTypeMaDH This is the protocol and version string to identify which protocol we expect.
protected byte[]	remotePreAuthenticationMessage
protected int	timeoutMs If !
protected java.io.OutputStreamWriter	toRemote The stream to send messages to the remote end.
protected int	totalTransferSize The number of bytes that have been transferred in both directions.
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

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

HostProtocolHandler(RemoteConnection con, java.util.Vector presharedShortSecrets, SimpleKeyAgreement permanentKeyAgreement, int timeoutMs, boolean keepConnected, boolean useJSSE)
This constructor should only be used by HostServerBase 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.
static byte[]	commitment(byte[] ownPublicKey, boolean useJSSE) This method implements the simplest possible commitment scheme for public Diffie-Hellman keys: a hash value on the key.
protected java.lang.String	getLine(java.lang.String expectedMsg, RemoteConnection remote, boolean allowOtherCommands) Tries to receive a properly formatted line from the remote host.
byte[]	getPreAuthenticationMessage() For the pre-authentication transfer case, this method returns our pre-authentication message.
static byte[]	keyedHash(byte[] oobInput, byte[] oobKey, boolean useJSSE) This method implements the keyed hash function for computing the l-Bit out-of-band message.
protected java.lang.Object[]	parseLine(java.lang.String line, java.lang.String expectedMsg, boolean[] isHexNumber, java.lang.String[] expectedParts, int numMandatoryParms, RemoteConnection remote) Tries to decode properly formatted Strings and numbers from the protocol line.
protected void	performAuthenticationProtocol(boolean serverSide) This method depends on prior initialization and assumes to be launched in an independent thread, i.e. it performs blocking operations.
protected void	println(java.lang.String line) Simple helper function for writing a line to the remote.
protected java.lang.String	readLine() Simple helper function for reading a line from the remote.
boolean	removeProtocolCommandHandler(java.lang.String command) Removes a protocol command handler.
void	setPreAuthenticationMessage(byte[] publicKeyCommitment) Set the remote pre-authentication message.
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) This is a convenience wrapper setting all options to null and thus starting the protocol in transfer or verification mode.
static void	startAuthenticationWith(RemoteConnection remote, AuthenticationProgressHandler eventHandler, SimpleKeyAgreement permanentKeyAgreementInstance, java.util.Vector presharedShortSecrets, byte[] remotePreAuthenticationMessage, 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

ProtocolTypeMaDH

public static final java.lang.String ProtocolTypeMaDH

This is the protocol and version string to identify which protocol we expect. May be changed for future improvements.

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

Protocol_AuthenticationAcknowledge2

public static final java.lang.String Protocol_AuthenticationAcknowledge2

See Also:

Protocol_Hello, Constant Field Values

Protocol_AuthenticationInputCommit

public static final java.lang.String Protocol_AuthenticationInputCommit

See Also:

Constant Field Values

Protocol_AuthenticationInputOpen

public static final java.lang.String Protocol_AuthenticationInputOpen

See Also:

Constant Field Values

AuthenticationStages

public static final int AuthenticationStages

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

See Also:

Constant Field Values

useJSSE

protected boolean useJSSE

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

timeoutMs

protected int timeoutMs

If != -1 and the protocol has been running for longer than this, it will be aborted.

keyAgreement

protected SimpleKeyAgreement keyAgreement

This holds the single instance of our (Diffie-Hellman) based key agreement protocol. For the "pre-authentication transfer" case, it will be initialized before the actual protocol starts to be able to commit to our public key. In all other cases, it will be initialized only as soon as necessary in the protocol run.

myPublicKey

protected byte[] myPublicKey

As soon as keyAgreement is initialized, this will also be set to our public key. It is the same as keyAgreement.getPublicKey() but cached here for better performance.

dontWipeKeyAgreement

protected boolean dontWipeKeyAgreement

If ephemeral Diffie-Hellman keys should not be used (for example, because this host must use permanent keys because its pre-authentication commitment is on a printed sticker that can't be changed), then this can be set to true. Be careful, though! Ephemeral keys should be used whenever possible!

connection

protected RemoteConnection connection

The (already opened) connection used to communicate with the remote end, for both incoming and outgoing connections.

keepConnected

protected boolean keepConnected

If set to false, connection will be closed after the protocol finished successfully. Setting this to true does not leave the connection open in all cases, because it will still be shut down on I/O errors (which are basically non-recoverable) or protocol errors (unexpected messages etc.).

See Also:

connection, #HostProtocolHandler(RemoteConnection, boolean, boolean)

optionalParameter

protected java.lang.String optionalParameter

An optional parameter that can be passed from the client to the server in its authentication request message. If not null, this message will be forwarded by both the server and the client in their respective authentication success messages.

toRemote

protected java.io.OutputStreamWriter toRemote

The stream to send messages to the remote end.

fromRemote

protected java.io.InputStream fromRemote

The stream to receive messages from the remote end.

totalTransferSize

protected int totalTransferSize

The number of bytes that have been transferred in both directions. At the moment, this counts ASCII bytes.

presharedShortSecrets

protected java.util.Vector presharedShortSecrets

If this is set, then we have some form of user input that has been created _before_ starting the 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!

remotePreAuthenticationMessage

protected byte[] remotePreAuthenticationMessage

Constructor Detail

HostProtocolHandler

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

This constructor should only be used by HostServerBase for incoming connections or with the static startAuthenticatingWith method for outgoing connections. It constructs the protocol in PlainObject style for transfer or comparison verification. The out-of-band message will be emitted via the AuthenticationSuccess message and the caller is responsible for using an appropriate auxiliary channel for key verification before using the session key.

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 asynchronicity: 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 open 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. Even when set to true, the connection will still be closed upon any protocol failure (e.g. I/O error or unparseable messages).

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.

HostProtocolHandler

public HostProtocolHandler(RemoteConnection con,
                           java.util.Vector presharedShortSecrets,
                           SimpleKeyAgreement permanentKeyAgreement,
                           int timeoutMs,
                           boolean keepConnected,
                           boolean useJSSE)

This constructor should only be used by HostServerBase for incoming connections or with the static startAuthenticatingWith method for outgoing connections. It constructs the protocol in PlainObject style for secret input verification and/or pre-authentication transfer. The secret user input (if not null) must already have been entered and must remain secret until AuthenticationSuccess (or failure) is emitted and must not be re-used. When this protocol instances finishes (successfully or not), it can still not be re-used and a fresh HostProtocolHandler object must always be created for each protocol run. However, the permanentKeyAgreement object passed in here (if not null) will not be wiped of its own key pair but only of the agreed session key (and the remote public key, of course). This allows another protocol instance to use the same key pair and thus generate the same pre-authentication commitment. The only sensible use-case for this constructor is when such static commitments must be used (for example, because it is printed on a sticker attached to the case of this device and therefore can't be changed). In all other cases avoid using this constructor. Although there are no known security weaknesses of using it, ephemeral Diffie-Hellman keys with a fresh keyAgreement object for each protocol run still add another layer of defense.

Parameters:

presharedShortSecrets - A list of secret, shared keys entered by the user on both sides before any interaction takes place on the wireless channel. This must remain secret until the protocol finishes and must not be re-used.
If the vector contains more than one entry, each 'candidate secret' will be tried in turn.
May be null, in which case no pre-shared short secret will be used.

permanentKeyAgreement - The key agreement instance (i.e. private and public Diffie-Hellman key pair) to be used. If set, it will not be wiped on protocol end. May be null, in which case a new, ephemeral key agreement instance will be created during the protocol run.

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.

readLine

protected java.lang.String readLine()
                             throws java.io.IOException

Simple helper function for reading a line from the remote.

Throws:

java.io.IOException

println

protected void println(java.lang.String line)
                throws java.io.IOException

Simple helper function for writing a line to the remote.

Throws:

java.io.IOException

getLine

protected java.lang.String getLine(java.lang.String expectedMsg,
                                   RemoteConnection remote,
                                   boolean allowOtherCommands)
                            throws java.io.IOException

Tries to receive a properly formatted line from the remote host. If the line could not be received (i.e. no line at all or starting with an unexpected command), an AuthenticaionFailure event is raised.

Parameters:

expectedMsg - Gives the message that is expected to be received.

remote - The remote socket. This is only needed for raising events and is passed unmodified to the event method.

allowOtherCommands - If true, then protocolCommandHandlers are checked when the received word does not match expectedMsg.

Returns:

The complete parameter line on success, null otherwise.

Throws:

java.io.IOException

parseLine

protected java.lang.Object[] parseLine(java.lang.String line,
                                       java.lang.String expectedMsg,
                                       boolean[] isHexNumber,
                                       java.lang.String[] expectedParts,
                                       int numMandatoryParms,
                                       RemoteConnection remote)
                                throws java.io.IOException

Tries to decode properly formatted Strings and numbers from the protocol line. If decoding fails, an AuthenticationFailure event is raised.

Parameters:

line - The complete line from the remote, including the command prefix.

expectedMsg - Gives the message that is expected to be received. This is simply cut off because we assume getLine already checked for this string to be present.

remote - The remote socket. This is only needed for raising events and is passed unmodified to the event method.

isHexNumber - This array both determines the number of parameters to try to decode and which of the parameters should be further decoded from String objects to Hex-coded integers.

expectedParts - If != null, then this array may contain parameters that are expected to be a equal to the constant string passed in here. All null elements are ignored.

numMandatoryParms - The number of parameters that _must_ be found in line after expectedMsg. It may be less than isHexNumber.length.

Returns:

The extracted parts are returned in this array, strings (i.e. non-number objects) as String objects, decoded numbers as byte arrays. If decoding failed, null will be returned instead of the (meaningless) parts that might have been decoded.

Throws:

java.io.IOException

commitment

public static byte[] commitment(byte[] ownPublicKey,
                                boolean useJSSE)
                         throws InternalApplicationException

This method implements the simplest possible commitment scheme for public Diffie-Hellman keys: a hash value on the key. There is no security proof for this scheme yet, as discussed in the original Mana IV article: Practical implementations [ZJC06,WUS06] of the MA-DH protocol use c = H(g^a) and such a relaxed security proof would bridge the gap between theory and practice. The current implementation uses SHA256-double for the commitment. Other options for implementing the commitment scheme according to the Mana IV article are: In reality, a cryptographic hash functions like SHA-1 are used instead of commitments, as such constructions are hundred times faster and there are no setup assumptions. Let H be a collision resistant hash function. Then the hash commitment is computed as (c, d) := Com(x, r) with c = H(x||r) and d = (x, r) or, as in HMAC, c = H(r XOR opad||H(r XOR ipad||x)) with d = r. Both constructions are a priori not hiding. We would like to have a provably secure construction. In theory, we could use one-wayness of H and define commitment with hard-core bits but this leads to large commitments. Instead, we use Bellare-Rogaway random oracle design principle to heuristically argue that a hash commitment based on the OAEP padding is a better alternative. Recall that the OAEP padding is c = H(s, t), s = (x||0^k0 ) XOR g(r), t = r XOR f(s). The corresponding commitment c along with d = r is provably hiding and binding if g is pseudorandom, f is random oracle, and H is collision resistant. A priori SHA-1 and SHA-512 are not known to be non-malleable, as it has never been a design goal. On the other hand, the security proof of OAEP shows CCA2 security (non-malleability) provided that H is a partial-domain one-way permutation.

Parameters:

ownPublicKey - This side's public key for MA-DH.

Returns:

Throws:

InternalApplicationException

keyedHash

public static byte[] keyedHash(byte[] oobInput,
                               byte[] oobKey,
                               boolean useJSSE)
                        throws InternalApplicationException

This method implements the keyed hash function for computing the l-Bit out-of-band message. It uses the standard HMAC-SHA256 construction.

Throws:

InternalApplicationException

performAuthenticationProtocol

protected void performAuthenticationProtocol(boolean serverSide)

This method depends on prior initialization and assumes to be launched in an independent thread, i.e. it performs blocking operations. It assumes that the socket variable already contains a valid, connected socket that can be used for communication with the remote authentication partner. fromRemote and toRemote will be initialized as streams connected to this socket. MANA-IV: 1. Alice computes (c, d) := Com_pk(ka) for random ka and sends (ma, c) to Bob. 2. Bob chooses random kb and sends (mb, kb) to Alice. 3. Alice sends d to Bob, who computes ka = Open_pk(c, d) and halts if ka = empty. Both parties compute a test value oob = h(ma || mb, ka, kb) from the received messages. 4. Both parties accept (ma, mb) iff the local l-bit test values ooba and oobb coincide. Specification: h is a keyed hash function with sub-keys ka, kb from a message space of commitment scheme. The hash function h and the public parameters pk of the commitment scheme are fixed and distributed by a trusted authority. /* MA-DH: 1. Alice computes (c, d) := Com_pk(ka) for ka = g^a, a = random and sends (ida, c) to Bob. 2. Bob computes kb = g^b for random b and sends (idb, kb) to Alice. 3. Alice sends d to Bob, who computes ka = Open_pk(c, d) and halts if ka = empty. Both parties compute sid = (ida, idb) and oob = h(sid, ka, kb) from the received messages. 4. Both parties accept key = (g^a)^b = (g^b)^a iff the l-bit test values ooba and oobb coincide. Specification: h is a keyed hash function with sub-keys ka, kb of G where G = g is a q element Decisional Diffie-Hellman group; G is a message space of commitment scheme. Public parameters pk and G are fixed and distributed by a trusted authority. Device identifiers ida and idb must be unique in time, for example, a device address followed by a session counter. In this implementation, Alice is the client and Bob the server. This protocol is only assumed to be secure for a bidirectional and authentic out-of-band channel.

Parameters:

serverSide - true for server side ("authenticator"), false for client side ("authenticatee")

getPreAuthenticationMessage

public byte[] getPreAuthenticationMessage()

For the pre-authentication transfer case, this method returns our pre-authentication message. It may be provided to the other side using its setPreAuthenticationMessage() method, which will make the protocol run non-interactive with regards to the out-of-band channel. Calling this method doesn't hurt in any case and is idempotent - it will always return the same message as long as the protocol run has not finished. The pre-authentication commitment may or may not be used.

Returns:

Our pre-authentication commitment to our public Diffie-Hellman key. This may be made public.

setPreAuthenticationMessage

public void setPreAuthenticationMessage(byte[] publicKeyCommitment)

Set the remote pre-authentication message. It will only influence the protocol when set before the protocol run actually starts. When set, no further out-of-band verification will be done.

Parameters:

publicKeyCommitment - The pre-authentication commitment to the remote public key as returned by the other side's getPreAuthenticationMessage() method and transmitted over an authentic channel. This is highly important for security: The pre-authentication commitment must be guaranteed to have been created by the legitimate remote device and have not been tampered with.

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,
                                           SimpleKeyAgreement permanentKeyAgreementInstance,
                                           java.util.Vector presharedShortSecrets,
                                           byte[] remotePreAuthenticationMessage,
                                           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. When presharedShortSecret is set to null, the protocol will use transfer or verification mode. When it is set to some value, secret pre-input mode is used.

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.

presharedShortSecret - If a user has already entered the same short secret key into both sides, it may be passed in this parameter to avoid further authentication via out-of-band channel. It is important this this must remain secret until the protocol finishes and that it must not be re-used.

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 passed into this method in the form of the remote parameter is not closed on success but passed to the authentation success event for further reuse. Even if set to true, it will be closed when any protocol failure occurs, though, because this most probably means that the connection itself suffers from I/O errors or that it is being tampered with.

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

startAuthenticationWith

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

This is a convenience wrapper setting all options to null and thus starting the protocol in transfer or verification mode.

Throws:

java.io.IOException

See Also:

startAuthenticationWith