org.openuat.authentication
Class CKPOverUDP

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

Direct Known Subclasses:

MotionAuthenticationProtocol2

public abstract class CKPOverUDP
extends AuthenticationEventSender

This is an abstract class that implements the basics of all protocols based on running a candidate key protocol over UDP. Man-in-the-middle attacks are not possible because there is no key agreement. Both hosts generate key part candidates, broadcast hashes of them and optionally flag matches. This way, matching candidate key parts form a shared key between the hosts. To be sure that lost packets do not cause creation of different keys, these keys are again acknowledged by exchanging hashes. For more details on the candidate key protocol, see @see CandidateKeyProtocol. The final verdict of the authentication protocol will be signalled by emitting standard authentication events (as defined by AuthenticationProgressHandler) and by calling either the protocolSucceededHook or the protocolFailedHook function. In short, the whole authentication protocol should be used as follows: 1. Construct the object. 2. Add potentially similar key material by calling addCandidates. 3. When a key could be generated from the matches given the requirements passed when constructing the object, its hash will be sent to the remote host and, upon receiving acknowledgement, the protocolSucceededHook will be called. TODO: Also emit protocol progress events (but what is max??) Generally, events will be emitted by this class to all registered listeners.

Version:

1.0

Author:

Rene Mayrhofer

Field Summary

protected java.lang.String	instanceId This may be set to distinguish multiple instances running on the same machine.
static int	Maximum_Udp_Data_Size The maximum size of the data transported in a single UDP packet over Ethernet: Ethernet maximum packet size is 1518, with an Ethernet header of 14 and a checksum of 4 Bytes.
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

protected

CKPOverUDP(int udpReceivePort, int udpSendPort, java.lang.String multicastGroup, java.lang.String instanceId, boolean broadcastCandidates, boolean sendMatches, int localCandidateHistorySize, int matchingPartsHistorySize, int maxMatchAge, float minMatchingRoundsFraction, float minMatchingEntropy, float maxMismatchRoundsFraction, int minNumRoundsForAction, boolean useJSSE) Construct the object by initializing basic variables.

Method Summary

protected void	addCandidates(byte[][] keyParts, float entropy) This method should be called whenever new key material for a round has been generated.
void	dispose() Takes care to close the UDPMulticastSocket resources properly and to wipe key material from the CandidateKeyProtocol instance.
protected abstract void	protocolFailedHook(java.lang.String remote, float matchingRoundsFraction, java.lang.Exception e, java.lang.String message) This hook will be called when the whole authentication protocol has failed.
protected abstract void	protocolProgressHook(java.lang.String remote, int cur, int max, java.lang.String message) This hook will be called when the whole authentication protocol has made some progress.
protected abstract void	protocolSucceededHook(java.lang.String remote, byte[] sharedSessionKey, float matchingRoundsFraction) This hook will be called when the final verdict is that the whole authentication protocol succeeded, i.e.

Methods inherited from class org.openuat.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

Maximum_Udp_Data_Size

public static final int Maximum_Udp_Data_Size

The maximum size of the data transported in a single UDP packet over Ethernet: Ethernet maximum packet size is 1518, with an Ethernet header of 14 and a checksum of 4 Bytes. IP header is usually XS bytes, UDP header is 8 bytes. --> 1492-X Bytes But set this large, because we don't really care about fragmentation.

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.

instanceId

protected java.lang.String instanceId

This may be set to distinguish multiple instances running on the same machine.

Constructor Detail

CKPOverUDP

protected CKPOverUDP(int udpReceivePort,
                     int udpSendPort,
                     java.lang.String multicastGroup,
                     java.lang.String instanceId,
                     boolean broadcastCandidates,
                     boolean sendMatches,
                     int localCandidateHistorySize,
                     int matchingPartsHistorySize,
                     int maxMatchAge,
                     float minMatchingRoundsFraction,
                     float minMatchingEntropy,
                     float maxMismatchRoundsFraction,
                     int minNumRoundsForAction,
                     boolean useJSSE)
              throws java.io.IOException

Construct the object by initializing basic variables.

Parameters:

udpReceivePort - The UDP port to use for listening to packets.

udpSendPort - The UDP target port to send packets to. Will usually be the same as the udpReceivePort.

multicastGroup - The multicast group to use for exchanging candidate key parts. When a unicast address is specified instead, special handling will be used. Only use a unicast address if you have read and understood the source code.

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.

instanceId - This parameter may be used to distinguish different instances of this class running on the same machine. It will be used in logging and error messages. May be set to null.

broadcastCandidates - If set to true, all candidate key part idenfifiers will be broadcast immediately after adding them to the local history. Set this to true if the local host should send out its generated candidates.

sendMatches - If set to true, all matches between candidate key part identifiers received over the network that match local key parts in the history will be acknowledged over the network. These acknowledgements are bound to leak some information about the matching key parts, although we currently assume that this leakage is of no use to an attacker because only hashes of key parts are broadcast. Set this to true if communication is very unreliable and it has to be assumed that candidate key part identifiers get lost, or in an asymmetric setting where one host broadcasts the candidate key part identifiers and the other acknowledges matches.

localCandidateHistorySize - The number of local candidates to keep in the history. If this is too small, matches might not be found. A good compromise between supporting asynchronity (which requires a large history) and minimizing required memory is 20 times the number of candidates that are created in each round, for many applications.

matchingPartsHistorySize - The number of matching key parts to keep in the history for each remote host. This needs to be large enough to hold sufficient entropy (i.e. number of parts) for creating a shared key. A good compromise between asynchronity (which requires a large history) and minimizing required memory and key search time if 10 times the minimum number of rounds for action times the number of candidates that are create in each round.

maxMatchAge - The maximum age, in seconds, to keep matches with remote hosts before pruning them. For many interactive protocols, 300 (5 minutes) is a good value.

minMatchingRoundsFraction - The minimum fraction of rounds that need at least one match before a key will be generated. The sum of minMatchingRoundsFraction and maxMismatchRoundsFraction must be <= 1.0, because a mismatch is defined as (1-match), and there must be a clear distinction between match and mismatch.

minMatchingEntropy - The minimum entropy that needs to be collected in matching key parts before a key will be generated.

maxMismatchRoundsFraction - The maximum fraction of rounds that are allowed to have no match before the protocol is aborted with an error. The sum of minMatchingRoundsFraction and maxMismatchRoundsFraction must be <= 1.0, because a mismatch is defined as (1-match), and there must be a clear distinction between match and mismatch.

minNumRoundsForAction - The minimum number of (local) rounds that need to pass with each remote host before any action (success or failure) is taken for that remote host.

Throws:

java.io.IOException

Method Detail

addCandidates

protected void addCandidates(byte[][] keyParts,
                             float entropy)
                      throws InternalApplicationException,
                             java.io.IOException

This method should be called whenever new key material for a round has been generated. It will trigger sending the associated identifiers when broadcastCandidates is set.

Parameters:

keyParts - The candidate key parts for this round.

entropy - An estimation of the entropy of all the key parts.

Throws:

InternalApplicationException

java.io.IOException

See Also:

broadcastCandidates

dispose

public void dispose()

Takes care to close the UDPMulticastSocket resources properly and to wipe key material from the CandidateKeyProtocol instance.

protocolSucceededHook

protected abstract void protocolSucceededHook(java.lang.String remote,
                                              byte[] sharedSessionKey,
                                              float matchingRoundsFraction)

This hook will be called when the final verdict is that the whole authentication protocol succeeded, i.e. both hosts signalled success on key verification.

Parameters:

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

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.

matchingRoundsFraction - The fraction of rounds where a match could be found.

protocolFailedHook

protected abstract void protocolFailedHook(java.lang.String remote,
                                           float matchingRoundsFraction,
                                           java.lang.Exception e,
                                           java.lang.String message)

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

Parameters:

remote - The remote host address with which the key exchange failed.

matchingRoundsFraction - The fraction of rounds where a match could be found. Will be set to 0 if unknown.

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

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

protocolProgressHook

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

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

Parameters:

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

cur - @see AuthenticationProgressHandler#AuthenticationProgress

max - @see AuthenticationProgressHandler#AuthenticationProgress

message - @see AuthenticationProgressHandler#AuthenticationProgress