org.openuat.channel.oob
Class ButtonChannel

java.lang.Object
  org.openuat.channel.oob.ButtonChannel

All Implemented Interfaces:

OOBChannel, ButtonInputHandler

Direct Known Subclasses:

ButtonToButtonChannel, FlashDisplayToButtonChannel, LongVibrationToButtonChannel, PowerBarToButtonChannel, ProgressBarToButtonChannel, ShortVibrationToButtonChannel, TrafficLightToButtonChannel

public abstract class ButtonChannel
extends java.lang.Object
implements OOBChannel, ButtonInputHandler

This class is a common ancestor for all button related oob channels. It provides much of the functionality which is needed in the capture and transmit methods but does not depend on a specific underlying platform.
All platform dependent calls are delegated to an appropriate instance of a subclass of ButtonChannelImpl.

Version:

1.0

Author:

Lukas Huser

See Also:

ButtonChannelImpl

Field Summary

static int	BITS_PER_INTERVAL From each interval between two button events, 3 bits of random data can be extracted.
protected java.lang.String	captureDisplayText Some text that is displayed while waiting for user input (button events).
protected boolean	doRoundDown Used for intervalsToBytes(org.openuat.util.IntervalList, int, int, boolean, boolean).
protected ButtonChannelImpl	impl Delegate platform dependent method calls to a ButtonChannelImpl instance.
protected int	inputMode The current input mode.
protected Log	logger Logger instance.
static int	MESSAGE_LENGTH Length of an oob message that can be sent over a button channel: 24 bit = 3 byte.
protected OOBMessageHandler	messageHandler oob message handler
protected int	minTimeUnit The smallest considered time unit in ms.
protected int	minTimeUnit2 The smallest considered time unit for a second verification run.
static int	MODE_PRESS Input mode: Press.
static int	MODE_PRESS_RELEASE Input mode: Press/Release.
protected java.lang.String	shortDescription A short description (one to two words) of the channel, suitable to print on a gui element e.g. to list several channels to choose from.
protected boolean	showFeedback Should additional user feedback be output?
protected Log	statisticsLogger Logger instance for statistics data.
static int	TOTAL_SIGNAL_COUNT The total number of signals needed to transfer a given message is given as the number of needed intervals plus one (n intervals are defined by n+1 signals).
protected java.lang.String	transmitDisplayText Some text that is displayed before (and, if the channels doesn't use the display itself to transmit, while) transmitting data.
protected boolean	useCarry Used for intervalsToBytes(org.openuat.util.IntervalList, int, int, boolean, boolean).

Fields inherited from interface org.openuat.authentication.OOBChannel

AUDIO_CHANNEL, BUTTON_CHANNEL, VIDEO_CHANNEL

Constructor Summary

ButtonChannel()

Method Summary

void	buttonPressed(long eventTime) Handles button press events.
void	buttonReleased(long eventTime) Handles button release events.
protected IntervalList	bytesToIntervals(byte[] bytes, int minInterval, int bitsPerInterval, int intervalCount) Converts a byte[] to an IntervalList, which is suitable to transmit data over a button channel.
void	capture() Receives out of band inputs.
protected byte[]	intervalsToBytes(IntervalList intervals, int minInterval, int bitsPerInterval, boolean roundDown, boolean useCarry) Converts an IntervalList to a byte[].
void	setOOBMessageHandler(OOBMessageHandler handler) Registers a handler for oob messages.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.openuat.authentication.OOBChannel

transmit

Field Detail

MESSAGE_LENGTH

public static final int MESSAGE_LENGTH

Length of an oob message that can be sent over a button channel: 24 bit = 3 byte.
This value should be a multiple of BITS_PER_INTERVAL.
Note: a high value results in low usability.

See Also:

Constant Field Values

BITS_PER_INTERVAL

public static final int BITS_PER_INTERVAL

From each interval between two button events, 3 bits of random data can be extracted.
(See C. Soriente, G. Tsudik: 'BEDA: Button-Enabled Device Association')

See Also:

Constant Field Values

TOTAL_SIGNAL_COUNT

public static final int TOTAL_SIGNAL_COUNT

The total number of signals needed to transfer a given message is given as the number of needed intervals plus one (n intervals are defined by n+1 signals).
It's defined as:
TOTAL_SIGNAL_COUNT = (MESSAGE_LENGTH / BITS_PER_INTERVAL) + 1.

See Also:

Constant Field Values

MODE_PRESS

public static final int MODE_PRESS

Input mode: Press. Button presses represent a button event, button releases are ignored.

See Also:

Constant Field Values

MODE_PRESS_RELEASE

public static final int MODE_PRESS_RELEASE

Input mode: Press/Release. Button presses and releases both represent a button event.

See Also:

Constant Field Values

impl

protected ButtonChannelImpl impl

Delegate platform dependent method calls to a ButtonChannelImpl instance.

minTimeUnit

protected int minTimeUnit

The smallest considered time unit in ms.
Needed to cope with reaction delays by the user. For transfer channels minTimeUnit / 2 corresponds to the maximum reaction delay.

minTimeUnit2

protected int minTimeUnit2

The smallest considered time unit for a second verification run. Only used for the input channel. If it is set to 0 (default), there won't be a second verification run.

inputMode

protected int inputMode

The current input mode. Can be either MODE_PRESS or MODE_PRESS_RELEASE.

doRoundDown

protected boolean doRoundDown

Used for intervalsToBytes(org.openuat.util.IntervalList, int, int, boolean, boolean).
true: round down
false: round nearest

useCarry

protected boolean useCarry

Used for intervalsToBytes(org.openuat.util.IntervalList, int, int, boolean, boolean).

showFeedback

protected boolean showFeedback

Should additional user feedback be output? As for example the current signal count etc.

messageHandler

protected OOBMessageHandler messageHandler

oob message handler

See Also:

setOOBMessageHandler(org.openuat.authentication.OOBMessageHandler)

captureDisplayText

protected java.lang.String captureDisplayText

Some text that is displayed while waiting for user input (button events). The field should be initialized by subclasses of this class, such that the text instructs or informs the user, according to the respective channel.

transmitDisplayText

protected java.lang.String transmitDisplayText

Some text that is displayed before (and, if the channels doesn't use the display itself to transmit, while) transmitting data. The text should be instructive

shortDescription

protected java.lang.String shortDescription

A short description (one to two words) of the channel, suitable to print on a gui element e.g. to list several channels to choose from.
The toString method is overridden and will output this value.

logger

protected Log logger

Logger instance. It will be used by this class and its subclasses as well.

statisticsLogger

protected Log statisticsLogger

Logger instance for statistics data. It will be used by this class and its subclasses as well.

Constructor Detail

ButtonChannel

public ButtonChannel()

Method Detail

capture

public void capture()

Receives out of band inputs. Listens to key press/release events and extracts the transmitted message from the captured time intervals.

Specified by:

capture in interface OOBChannel

setOOBMessageHandler

public void setOOBMessageHandler(OOBMessageHandler handler)

Registers a handler for oob messages. The handler will be invoked after an oob message has been received by the capture method.

Specified by:

setOOBMessageHandler in interface OOBChannel

Parameters:

handler - oob message handler

buttonPressed

public void buttonPressed(long eventTime)

Description copied from interface: ButtonInputHandler

Handles button press events.

Specified by:

buttonPressed in interface ButtonInputHandler

Parameters:

eventTime - Exact time of the event in milliseconds. Provided by the underlying platform.

buttonReleased

public void buttonReleased(long eventTime)

Description copied from interface: ButtonInputHandler

Handles button release events.

Specified by:

buttonReleased in interface ButtonInputHandler

Parameters:

eventTime - Exact time of the event in milliseconds. Provided by the underlying platform.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

intervalsToBytes

protected byte[] intervalsToBytes(IntervalList intervals,
                                  int minInterval,
                                  int bitsPerInterval,
                                  boolean roundDown,
                                  boolean useCarry)

Converts an IntervalList to a byte[].
bitsPerInterval should not exceed 31, it is truncated to 31 if it's larger. The result is at most 64 bit = 8 byte long. If intervals.size() * max(bitsPerInterval, 31) exceeds 64 bit, only the first 64 bits will be returned. If the returned number of bits is not a multiple of 8, the remaining bits in the last byte are set to zero.

Parameters:

intervals - The list of intervals to be converted.

minInterval - Smallest considered interval or time unit in ms.

bitsPerInterval - How many bits per interval should be extracted?

roundDown - Rounding mode: If true, each interval will be rounded down to the next multiple of minInterval. If false, each interval will be rounded to the nearest multiple of minInterval.

useCarry - Should rounding losses be added to the next interval?

Returns:

Returns the message converted to a byte[].

See Also:

IntervalList

bytesToIntervals

protected IntervalList bytesToIntervals(byte[] bytes,
                                        int minInterval,
                                        int bitsPerInterval,
                                        int intervalCount)

Converts a byte[] to an IntervalList, which is suitable to transmit data over a button channel.
The length of bytes should not exceed 8 bytes, only the first 8 bytes will be considered. bitsPerInterval should not exceed 31, it is truncated to 31 if it's larger.

Parameters:

bytes - The input to be converted to an IntervalList.

minInterval - Minimum length of a generated interval.

bitsPerInterval - How many bits are encoded in a generated interval?

intervalCount - How many intervals will be generated? This parameter must be consistent with the length of bytes and bitsPerInterval. It is useful, if the message doesn't align with 1 byte, this is, if there are 'unused' bits in the last byte.

Returns:

Returns the message converted to an IntervalList.

See Also:

IntervalList