ostore.mac
Class HMACDHHandler

java.lang.Object
  |
  +--ostore.mac.MacHandler
        |
        +--ostore.mac.HMACDHHandler

All Implemented Interfaces:

EventHandlerIF, ProfilableIF, SingleThreadedEventHandlerIF

public class HMACDHHandler

extends MacHandler

MacHandler that uses HMAC for the message authentication and Diffie-Hellman Key Generation.



Station-To-Station Protocol Implentation:



Basic Protocol:

There are four states: (1)UNINITIALIZED, (2)WAITFORRESPONSE, (3)WAITFORFINAL, (4)ESTABLISHED.

There are three messages (across the network): (1)INITIALIZE, (2)RESPOND, (3)FINALIZE.

There are three events (internal): (1)INIT (request to send out message 1), (2) STS_TIMEOUT, (3)DH_TIMEOUT

State table

State	Event	Next Stage	Action
UNINIT	DD sends (1)INIT event	WAITFORRESPONSE	Send message (1)
UNINIT	Receive message (1)	WAITFORFINAL	Compute secret, Send message (2)
WAITFORRESPONSE	Receive message (2)	ESTABLISHED	Confirm signature and Compute secret, Send message (3)
WAITFORRESPONSE	Receive message (1)	WAITFORRESPONSE or WAITFORFINAL	If my guid is greater that their guid, I become WAITFORFINAL, else ignore message.
WAITFORFINAL	Receive message (3)	ESTABLISHED	Confirm signature

establishedParties & pendingParties:

Needed: To be able to go through a false or faulty handshake, one that is cancelled before completion, and not lose the existing connection.

Solution: Keep two Hashtables (indexed by guid) one for established connections (establishedParties) and another for in-progress connections (pendingParties). If a pendingParties connection successfully finishes a handshake, that entry replaces the one in establishedParties.

Functional access to this MacHandler only accesses establishedParties



Timeouts:

The HMACDHHandler handles timeouts (both session and Diffie-Hellman key expirations) by sending itself delayed messages. The time (in milliseconds) of these are determined by config variables: timeoutlength and dhlifespan



TODO describe sts timeout and dh timeout

Synchronicity:

Internally: establishedPartiesI This stage is not designed to be replicated. Replication may introduce race conditions that have not been thoroughly investigated.

Nested Class Summary

static class	HMACDHHandler.MacBuffer
protected class	HMACDHHandler.TellDhTimeout
protected class	HMACDHHandler.TellInit
protected class	HMACDHHandler.TellStsTimeout

Nested classes inherited from class ostore.mac.MacHandler

MacHandler.GuidNotEstablished, MacHandler.HandshakeFailed, MacHandler.KeyEstablished

Field Summary

protected Classifier	_classifier
protected int	_dhlifespan
protected Mac	_hmac
protected KeyAgreement	_kagree
protected static int	_keysize
protected KeyPairGenerator	_kpgen
protected SecureHash	_myGuid
protected String	_pkeyfile
protected SecureRandom	_r
protected int	_retryLimit
protected boolean	_selfTest
protected Signature	_signEngine
protected QSPrivateKey	_sigPri
protected QSPublicKey	_sigPub
protected String	_skeyfile
protected int	_stsTime
protected SinkIF	_this_sink
static boolean	ANNOUNCE
static boolean	DEBUG
protected Hashtable	establishedParties
protected static Hashtable	instances
protected long	MACTYPE_HMACMD5
protected Hashtable	pendingParties
static boolean	SEAN_DEBUG
static String	tag

Constructor Summary

HMACDHHandler()

Method Summary

boolean	authenticate(QuickSerializable user_data, QSByteArray incoming_mac, SecureHash guid) Note: a failure may mean that a message was sent right before the sender decided to change keys that that message arrived after a new key was established (though this is unlikely) it is a possibility that needs to be accounted for.
protected static void	BUG(String msg)
protected boolean	checkDHVerify(QuickSerializable user_data, QSByteArray mac, DHMessage dhmsg, PartyInfo info)
void	destroy()
protected void	dispatch(QueueElementIF item)
QSByteArray	doMAC(QuickSerializable user_data, SecureHash guid) Computes the MAC code for the this message
void	establish(SecureHash guid) Establish a connection between the guid and this instance of sandstorm Once a connection is established, the MacHandler will broadcast a MacHandler.KeyEstablished announcement.
static HMACDHHandler	getInstance(SecureHash guid) Return the HMACDHHandler associated with a particular guid.
void	handle_dh_message(DHMessage dhmsg) Need these to happen before processing subsequent messages, so we call it from the Router directly now.
protected void	handle_dh_timeout(HMACDHHandler.TellDhTimeout tell)
protected void	handle_init(HMACDHHandler.TellInit tell)
protected void	handle_state_uninit(DHMessage dhmsg, int msgType, SecureHash otherguid, PartyInfo info)
protected void	handle_state_waitforfin(DHMessage dhmsg, int msgType, SecureHash otherguid, PartyInfo info)
protected void	handle_state_waitforresp_init(DHMessage dhmsg, SecureHash otherguid, PartyInfo info)
protected void	handle_state_waitforresp_resp(DHMessage dhmsg, SecureHash otherguid, PartyInfo info)
protected void	handle_sts_timeout(HMACDHHandler.TellStsTimeout tell)
void	handleEvent(QueueElementIF item)
void	handleEvents(QueueElementIF[] item)
String	idString() Id String
void	init(ConfigDataIF config)
protected void	makeDHVerify(QSDHPublicKey myPu, QSDHPublicKey otherPu, SecretKey macSecret, DHMessage destination)
protected void	makeNewDHKeys(PartyInfo info)
SecureHash	myGuid() My GUID
int	profileSize()

Methods inherited from class java.lang.Object

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

Field Detail

tag

public static final String tag

See Also:

Constant Field Values

SEAN_DEBUG

public static final boolean SEAN_DEBUG

See Also:

Constant Field Values

DEBUG

public static final boolean DEBUG

See Also:

Constant Field Values

ANNOUNCE

public static final boolean ANNOUNCE

See Also:

Constant Field Values

_keysize

protected static final int _keysize

See Also:

Constant Field Values

instances

protected static Hashtable instances

establishedParties

protected Hashtable establishedParties

pendingParties

protected Hashtable pendingParties

_kpgen

protected KeyPairGenerator _kpgen

_kagree

protected KeyAgreement _kagree

_r

protected SecureRandom _r

_signEngine

protected Signature _signEngine

_pkeyfile

protected String _pkeyfile

_skeyfile

protected String _skeyfile

_sigPub

protected QSPublicKey _sigPub

_sigPri

protected QSPrivateKey _sigPri

_hmac

protected Mac _hmac

_myGuid

protected SecureHash _myGuid

_this_sink

protected SinkIF _this_sink

_stsTime

protected int _stsTime

_retryLimit

protected int _retryLimit

_dhlifespan

protected int _dhlifespan

_selfTest

protected boolean _selfTest

_classifier

protected Classifier _classifier

MACTYPE_HMACMD5

protected long MACTYPE_HMACMD5

Constructor Detail

HMACDHHandler

public HMACDHHandler()

Method Detail

handle_init

protected void handle_init(HMACDHHandler.TellInit tell)

handle_sts_timeout

protected void handle_sts_timeout(HMACDHHandler.TellStsTimeout tell)

handle_dh_timeout

protected void handle_dh_timeout(HMACDHHandler.TellDhTimeout tell)

handle_state_uninit

protected void handle_state_uninit(DHMessage dhmsg,
                                   int msgType,
                                   SecureHash otherguid,
                                   PartyInfo info)

handle_state_waitforresp_resp

protected void handle_state_waitforresp_resp(DHMessage dhmsg,
                                             SecureHash otherguid,
                                             PartyInfo info)

handle_state_waitforresp_init

protected void handle_state_waitforresp_init(DHMessage dhmsg,
                                             SecureHash otherguid,
                                             PartyInfo info)

handle_state_waitforfin

protected void handle_state_waitforfin(DHMessage dhmsg,
                                       int msgType,
                                       SecureHash otherguid,
                                       PartyInfo info)

handle_dh_message

public void handle_dh_message(DHMessage dhmsg)

Description copied from class: MacHandler

Need these to happen before processing subsequent messages, so we call it from the Router directly now.

Specified by:

handle_dh_message in class MacHandler

handleEvent

public void handleEvent(QueueElementIF item)
                 throws EventHandlerException

Specified by:

handleEvent in interface EventHandlerIF

Specified by:

handleEvent in class MacHandler

EventHandlerException

handleEvents

public void handleEvents(QueueElementIF[] item)
                  throws EventHandlerException

Specified by:

handleEvents in interface EventHandlerIF

Overrides:

handleEvents in class MacHandler

EventHandlerException

checkDHVerify

protected boolean checkDHVerify(QuickSerializable user_data,
                                QSByteArray mac,
                                DHMessage dhmsg,
                                PartyInfo info)
                         throws InvalidKeyException,
                                SignatureException,
                                TypeTable.NoSuchTypeCode

InvalidKeyException

SignatureException

TypeTable.NoSuchTypeCode

makeDHVerify

protected void makeDHVerify(QSDHPublicKey myPu,
                            QSDHPublicKey otherPu,
                            SecretKey macSecret,
                            DHMessage destination)
                     throws SignatureException,
                            InvalidKeyException

SignatureException

InvalidKeyException

makeNewDHKeys

protected void makeNewDHKeys(PartyInfo info)

init

public void init(ConfigDataIF config)
          throws Exception

Specified by:

init in interface EventHandlerIF

Specified by:

init in class MacHandler

Exception

getInstance

public static HMACDHHandler getInstance(SecureHash guid)

Return the HMACDHHandler associated with a particular guid.

establish

public void establish(SecureHash guid)

Establish a connection between the guid and this instance of sandstorm

Once a connection is established, the MacHandler will broadcast a MacHandler.KeyEstablished announcement.

Specified by:

establish in class MacHandler

authenticate

public boolean authenticate(QuickSerializable user_data,
                            QSByteArray incoming_mac,
                            SecureHash guid)
                     throws MacHandler.GuidNotEstablished

Note: a failure may mean that a message was sent right before the sender decided to change keys that that message arrived after a new key was established (though this is unlikely) it is a possibility that needs to be accounted for.

Specified by:

authenticate in class MacHandler

Returns:

true iff this message is authentic, i.e. verified by the internal MAC

MacHandler.GuidNotEstablished

doMAC

public QSByteArray doMAC(QuickSerializable user_data,
                         SecureHash guid)
                  throws MacHandler.GuidNotEstablished

Computes the MAC code for the this message

Returns:

true iff the MAC was computed successfully.

MacHandler.GuidNotEstablished

idString

public String idString()

Description copied from class: MacHandler

Id String

Specified by:

idString in class MacHandler

myGuid

public SecureHash myGuid()

Description copied from class: MacHandler

My GUID

Specified by:

myGuid in class MacHandler

destroy

public void destroy()
             throws Exception

Specified by:

destroy in interface EventHandlerIF

Specified by:

destroy in class MacHandler

Exception

profileSize

public int profileSize()

Specified by:

profileSize in interface ProfilableIF

Specified by:

profileSize in class MacHandler

BUG

protected static final void BUG(String msg)

dispatch

protected void dispatch(QueueElementIF item)