org.openuat.authentication
Class InterlockProtocol

java.lang.Object
  org.openuat.authentication.InterlockProtocol

public class InterlockProtocol
extends java.lang.Object

This class implements the interlock protocol as first defined in Ronald L. Rivest and Adi Shamir: "How to Expose an Eavesdropper", 1984. It uses AES, either with the JSSE/JCE or with the Bouncycastle light API, because the latter can also run on e.g. J2ME devices without JCE support. Attention:The messages that are to be encrypted by interlock are assumed not to be private, i.e. that they can be revealed after the interlock protocol has completed or that information about them can be leaked. These can e.g. be nonces or other pseudo-random streams that have meaning to the receiver (for independent checking that no man-in-the-middle attack is happening) but do not need to be concealed afterwards. Nonetheless, a random nonce is used as initialization vector (IV) when the whole plain text message does not fit into a single block (i.e. 128 Bits). Note: When the plain text message fits into 128 Bits, it is assumed to be a nonce and ECB is used. A "stream-cipher" mode like OFB or CTR might produce less overhead (the IV would not need to be transmitted), but it still needs to be analyzed if this use would compromise the security properties of the interlock protocol. Currently, I do not think that it would, but feel uncomfortable using them without further thought about the implications.

Version:

1.0

Author:

Rene Mayrhofer

Constructor Summary

InterlockProtocol(byte[] sharedKey, int rounds, int numMessageBits, java.lang.String instanceId, boolean useJSSE)
Initializes the interlock protocol by setting all parameters that must be immutable for a single instance of the protocol.

Method Summary

boolean	addMessage(byte[] message, int round) Adds a message to the cipher text assemply.
boolean	addMessage(byte[] message, int offset, int numBits, int round) Adds a message to the cipher text assembly.
static void	addPart(byte[] dest, byte[] src, int bitOffset, int bitLen) Small helper function to add a part to a byte array.
byte[]	decrypt(byte[] cipherText) Decrypt the cipher text message with the shared key set in the constructor.
byte[]	encrypt(byte[] plainText) Encrypt the plain text message with the shared key set in the constructor.
static void	extractPart(byte[] dest, byte[] src, int bitOffset, int bitLen) Small helper function to extract a part from a byte array.
int	getCipherTextBlocks() Returns the number of cipher text blocks necessary to encode the message.
static byte[]	interlockExchange(byte[] message, java.io.InputStream fromRemote, java.io.OutputStream toRemote, byte[] sharedKey, int rounds, boolean protectAgainstMirrorAttack, boolean retransmit, int timeoutMs, boolean useJSSE, java.util.BitSet interlockGroup, int groupSize, int instanceInGroup) This method runs a complete interlock exchange with another host.
byte[]	reassemble() This method only checks that all rounds have actually been received (i.e. that they have been added with one of the addMessage methods) and, if everything is ok, returns the assmbled cipher text.
byte[]	reassemble(byte[][] messages) This method is the inverse of split().
byte[][]	split(byte[] cipherText) This method splits the cipher text into multiple parts for transmission in an interlocked way.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InterlockProtocol

public InterlockProtocol(byte[] sharedKey,
                         int rounds,
                         int numMessageBits,
                         java.lang.String instanceId,
                         boolean useJSSE)

Initializes the interlock protocol by setting all parameters that must be immutable for a single instance of the protocol.

Parameters:

sharedKey - The shared key to use for encryption and decryption.

rounds - The number of rounds to use for the protocol. Must be at least 2 and at most equal to the number of bits in the plain text message.

numMessageBits - The size of the plain text message that should be transmitted, measured in Bits.

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

Method Detail

encrypt

public byte[] encrypt(byte[] plainText)
               throws InternalApplicationException

Encrypt the plain text message with the shared key set in the constructor. If the message length equals the block size of the cipher, it is assumed to be a nonce and is encrypted as a single block in ECB mode. If it is larger, it is encrypted in CBC mode with a random IV prepended.

Parameters:

plainText - The message to encrypt. It must contain exactly as many bits as specified in the numMessageBits parameter in the constructor.

Returns:

The cipher text, which is either one block long or the number of blocks necessary to encrypt numMessageBits plus one block for the IV.

Throws:

InternalApplicationException

decrypt

public byte[] decrypt(byte[] cipherText)
               throws InternalApplicationException

Decrypt the cipher text message with the shared key set in the constructor. If the message length equals the block size of the cipher, the plain text is assumed to have been a nonce and is decrypted as a single block in ECB mode. If it is larger, it is decrypted in CBC mode with a random IV prepended.

Parameters:

cipherText - The cipher text to decrypt. It must be either one block long or the number of blocks necessary to encrypt numMessageBits plus one block for the IV.

Returns:

The plain text, which contains exactly as many bits as specified in the numMessageBits parameter in the constructor.

Throws:

InternalApplicationException

split

public byte[][] split(byte[] cipherText)
               throws InternalApplicationException

This method splits the cipher text into multiple parts for transmission in an interlocked way. The caller has to make sure that part i+1 is not sent until the other host has acknowledged receipt of part i and sent its part i. If this is not followed, the interlock protocol is not secure! How the splitting is done depends on the mode of the protocol: In the single-block case, the cipher text consists of just a single block encrypted by one call to the block cipher. Thus, this block is simply split into equally sized parts (besides the last one) taken one after the other from the cipher text. In the multi-block case, all blocks are split as in the single-block case and the parts of the independent blocks are then concatenated to form the parts. This makes sure that no single block can be decrypted before all of the message parts have been delivered.

Parameters:

cipherText - The cipher text to split.

Returns:

As many parts as there are rounds in the protocol in the first dimension of the returned array. The last arrays may be set to null if the cipher text does not split cleanly and the last rounds therefore do not contain any bits. The last array that is not null may be smaller than the previous arrays, but all other are equally sized. The last byte in each array might be padded with 0 on the top, i.e. the array will be filled from the LSB part.

Throws:

InternalApplicationException

reassemble

public byte[] reassemble(byte[][] messages)
                  throws InternalApplicationException

This method is the inverse of split(). All comments there apply here.

Parameters:

messages - The parts to reassemble.

Returns:

The assembled cipher text.

Throws:

InternalApplicationException

reassemble

public byte[] reassemble()

This method only checks that all rounds have actually been received (i.e. that they have been added with one of the addMessage methods) and, if everything is ok, returns the assmbled cipher text.

Returns:

The assembled cipher text if it has been received completely, or null in case of an error.

See Also:

addMessage(byte[], int), addMessage(byte[], int, int, int), assembledCipherText

addMessage

public boolean addMessage(byte[] message,
                          int offset,
                          int numBits,
                          int round)
                   throws InternalApplicationException

Adds a message to the cipher text assembly. This method should only be used if not the whole message is to be transferred and/or the application has very specific needs concerning re-assembly. Better use the simple addMessage variant unless sure you need this method.

Parameters:

message - The message to add.

offset - The bit offset where this message part starts in the reassembly.

numBits - The number of bits to take from the message array.

round - The round number of this message. Rounds are counted from 0 to rounds-1.

Returns:

true if added successfully, false if not added. When false is returned, then the part for this round has already been added earlier.

Throws:

InternalApplicationException

interlockExchange

public static byte[] interlockExchange(byte[] message,
                                       java.io.InputStream fromRemote,
                                       java.io.OutputStream toRemote,
                                       byte[] sharedKey,
                                       int rounds,
                                       boolean protectAgainstMirrorAttack,
                                       boolean retransmit,
                                       int timeoutMs,
                                       boolean useJSSE,
                                       java.util.BitSet interlockGroup,
                                       int groupSize,
                                       int instanceInGroup)
                                throws java.io.IOException,
                                       InternalApplicationException

This method runs a complete interlock exchange with another host. To this end, this method must be started on both sides with the same values for the number of rounds and, obviously, for the shared key.

Parameters:

message - The message to send to the remote host.

fromRemote - This stream is used for receiving bytes from the remote host. This method takes care not to consume any more bytes than stricly necessary, so that this stream can be re-used for subsequent communication betweem the hosts.

toRemote - This stream is used for sending bytes to the remote host.

sharedKey - The shared key to use for encryption and decryption. Must be equal on both sides or the messages will not decrypt successfully (and this indicates a man-in-the-middle attack).

rounds - The number of rounds to use.

protectAgainstMirrorAttack - When set to true, an additional check will be activated to protect against the "mirror attack", where a remote attacker (e.g. a MITM) simply mirrors all the interlock messages, to the effect that this method would return a remote message that was exactly equal to the local message. The upper layers that call this method may not be able to detect this case. Note that this protection can currently only be enabled when message.length is greater than SimpleBlockCipher.BlockByteLength. It is strongly recommended to set this to true, unless the upper protocol layers protect against this attack.

retransmit - Is set to true, lost messages are allowed and rounds will be retransmitted until the other end acknowledges it or a timeout occurs. THIS IS CURRENTLY NOT IMPLEMENTED. SET TO FALSE.

timeoutMs - If retransmit is set to true, every round will be limited to take this amount of milliseconds. If the other side has not acknowledged the receipt within this time, the protocol aborts. The overall timeout of the whole protocol is therefore defined to be a maximum of timeoutMs*rounds, but a timeout error may occur earlier than this. Set to 0 to disable timeouts (which is not recommended!).
Attention:Because of long-standing JRE bug 4514257 (see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4514257), it is impossible to cleanly interrupt the block read() on fromRemote. Therefore, when a timeout is triggered while waiting for the remote host to send (either the initial interlock greeting or it respective round number), then fromRemote will be closed. This is currently the only way of enforcing the timeout on blocking reads, and unfortunately makes it impossible to explicitly signal abort to the remote. In the case of toRemote being closed, one must therefore assume any abort reason from the remote including regular timeout aborts.

interlockGroup - Setting this to a valid BitSet object and groupSize>=2 allows for multiple instances of interlockExchange runs to be synchronized. All instances will enter a barrier just before transmitting their last round and will only continue to transmit when all instances (the number of instances in the group that are to be synchronized is specified by groupSize) have reached this barrier. This is necessary when the same message is used in multiple interlock instances to prevent an attack where multiple attackers are colluding. Set to null to disable when only one interlock instance is used with the same message. Using this function may increase the total timeout to timeoutMs*rounds*2.

groupSize - When interlockGroup is set, this specifies the number of instances to synchronize. Must be >=2, and all instances must be called in parallel threads with the same interlockGroup object.

instanceInGroup - The instance number in the group that this interlock run should use. No two instances may use the same number, and every number in [0; groupSize-1] must be used for exactly one instance.

Returns:

The message that the remote host sent, or null if the interlock protocol could not be completed successfully.

Throws:

java.io.IOException - When reading from fromRemote or writing to toRemote failed. This may also be caused by a timeout that forcefully closed fromRemote.

InternalApplicationException

addMessage

public boolean addMessage(byte[] message,
                          int round)
                   throws InternalApplicationException

Adds a message to the cipher text assemply. This is a convenience wrapper around the other addMessage method, which computes offset and numBits appropriately, assuming that the whole message (whose length was given to the constructor) is to be transmitted within the interlock rounds. This method should be used in favor of the other one, unless the application has very specific needs.

Parameters:

message - The message to add.

round - The round number of this message. Rounds are counted from 0 to rounds-1.

Returns:

true if added successfully, false if not added. When false is returned, then the part for this round has already been added earlier. It still returns true when the part was not added because the cipher text was already complete without it (this can only happen when the number of bits to be transmitted fits into less rounds than were used).

Throws:

InternalApplicationException

extractPart

public static void extractPart(byte[] dest,
                               byte[] src,
                               int bitOffset,
                               int bitLen)
                        throws InternalApplicationException

Small helper function to extract a part from a byte array. This method is only public for the JUnit tests, there's probably not much use for it elsewhere.

Parameters:

dest - The byte array to put the part into. It is assumed that it has been allocated with sufficient length.

src - The byte array from which the part should be extracted. It will be taken from the LSB part.

bitOffset - The number of bits to shift src before adding to dest.

bitLen - The number of bits to add from src to dest.

Throws:

InternalApplicationException

addPart

public static void addPart(byte[] dest,
                           byte[] src,
                           int bitOffset,
                           int bitLen)
                    throws InternalApplicationException

Small helper function to add a part to a byte array. This method is only public for the JUnit tests, there's probably not much use for it elsewhere.

Parameters:

dest - The byte array to add to. It is assumed that it has been allocated with sufficient length.

src - The part to add to dest. It will be added from the LSB part.

bitOffset - The number of bits to shift src before adding to dest.

bitLen - The number of bits to add from src to dest.

Throws:

InternalApplicationException

getCipherTextBlocks

public int getCipherTextBlocks()

Returns the number of cipher text blocks necessary to encode the message.