hypercast
Class SecurityProcessor

java.lang.Object
  |
  +--hypercast.NotificationHandler
        |
        +--hypercast.SecurityProcessor
All Implemented Interfaces:
I_AdapterCallback, I_IPv4_UnicastAdapter, I_MulticastAdapter, I_Stats, I_UnicastAdapter

public class SecurityProcessor
extends NotificationHandler
implements I_Stats, I_AdapterCallback, I_MulticastAdapter

This class defines the functions for handling the sending/receiving of secure messages. Once the instance of this class is created, it works as the node adapter for an overlay node and builds a bridge between the overlay node and the normal node adapter. The relationship between the overlay node, security processor and normal node adapter are represented by the following two chains: (I_AdapterCallBack object) node <- ((I_AdapterCallBack object) this object <- (I_UnicastAdapter) adapter node -> (I_UnicastAdapter) this object -> (I_AdapterCallBack object) adapter


Field Summary
 
Fields inherited from interface hypercast.I_IPv4_UnicastAdapter
MAX_RETRIES_TO_OPEN_SOCKET
 
Fields inherited from interface hypercast.I_UnicastAdapter
CLOSED, STARTED, STARTING, STOPPED, STOPPING
 
Constructor Summary
SecurityProcessor(hypercast.HyperCastConfig c, hypercast.KeyVault keyvault, hypercast.I_UnicastAdapter _adapter)
          Constructor.
 
Method Summary
 void clearSecurityTimer(java.lang.Object timer_id)
          Clear a SecurityTimer event
 void clearTimer(java.lang.Object timer_id)
          Clear a Timer event
 void close()
          pass the close call down to the adapter.
 hypercast.I_AddressPair createAddressPair(hypercast.I_PhysicalAddress pa, hypercast.I_LogicalAddress la)
          Create an address pair from a physical address and a logical address.
 hypercast.I_PhysicalAddress createPhysicalAddress()
          Creates a new physical address.
 hypercast.I_PhysicalAddress createPhysicalAddress(byte[] byteaddr, int offset)
          Creates physical address from a byte array.
 hypercast.I_PhysicalAddress createPhysicalAddress(java.lang.String addrString)
          Creates physical address from a string.
 hypercast.I_UnderlayAddress createUnderlayAddress()
          Creates a new underlay address.
 hypercast.I_UnderlayAddress createUnderlayAddress(byte[] byteAddressAndPort, int offset)
          Creates underlay address from a byte array of address - the inverse of toByteArray.
 hypercast.I_UnderlayAddress createUnderlayAddress(java.lang.String addrString)
          Creates underlay address object from a string.
 hypercast.I_UnicastAdapter getAdapter()
           
 hypercast.I_AdapterCallback getCallBack()
           
 long getCurrentTime()
          Gets the current time.
 java.lang.Object getInfo()
          Get information of the adapter.
 hypercast.KeyVault getKeyVault()
          Gets the key vault object kept by this object.
 hypercast.I_PhysicalAddress getMulticastAddress()
          Gets the multicast address of the adapter.
 javax.crypto.spec.SecretKeySpec getMyKeyFor(hypercast.I_AddressPair dst_ap, hypercast.I_AddressPair src_ap)
          The function return the key that the local node is exchanging with a remote destination node.
 long getMyKeyTimestampFor(hypercast.I_AddressPair dst_ap, hypercast.I_AddressPair src_ap)
           
 hypercast.I_Node getNode()
           
 int getPhysicalAddressSize()
          Returns the size of physical address, when carried in a packet, recognized by this adapter.
 org.w3c.dom.Element[] getReadSchema(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Return the schema element which represents the root of the sub-tree, specified by the given xpath, in read schema tree.
 long getSecurityTimer(java.lang.Object timer_id)
          Get a SecurityTimer event
 org.w3c.dom.Element[] getStats(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Return the result of query for the statistics specified by the given xpath.
 java.lang.String getStatsName()
          Gets the element name of the adapter.
 long getTimer(java.lang.Object timer_id)
          Get a Timer event
 int getUnderlayAddressSize()
          Returns the size of underlay address, when carried in a packet, recognized by this adapter.
 java.lang.String getVersion()
           
 org.w3c.dom.Element[] getWriteSchema(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Return the schema element which represents the root of the sub-tree, specified by the given xpath, in write schema tree.
 void handle_NODE_NEIGHBORHOODCHANGED(hypercast.events.NODE_NEIGHBORHOODCHANGED event)
          Handle neighborhood change event.
 void initiateAuthentication(hypercast.I_AddressPair src)
          Initialize certificate exchange process with given node.
 void messageArrivedFromAdapter(hypercast.I_Message a)
          Checks all incoming protocol messages for security extensions and performs appropriate integrity checks and/or decryption before handing the message to the node to process.
 void requestKeyFor(hypercast.I_LogicalAddress nodeLA)
          Initiate a key exchange with a node
 boolean Reset(java.lang.Object socketObj)
          Reset the sockets in the adapter.
 hypercast.I_Message restoreMessage(byte[] receiveBuffer, int[] validBytesStart, int validBytesEnd)
          Restore an SecInfoExchange_Message from byte array.
 void sendMulticastMessage(hypercast.I_Message msg)
          Sends out a multicast message.
 void sendUnicastMessage(hypercast.I_NetworkAddress dst, hypercast.I_Message msg)
          Sends out an unicast message.
 void setAdapter(hypercast.I_UnicastAdapter adapter)
          Sets the adapter stored in the instance of this class.
 void setCallback(hypercast.I_AdapterCallback adaptercallbackObj)
          Set the adapter callback object.
 void setLastSecureMessageTime(hypercast.I_LogicalAddress nodeLA)
          Set the time when the last secure message was received from the given node.
 void setNode(hypercast.I_Node node)
          Sets the overlay node stored in the instance of this class.
 void setSecurityTimer(java.lang.Object timer_id, long delay_ms)
          Set a SecurityTimer event
 org.w3c.dom.Element[] setStats(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath, org.w3c.dom.Element newValue)
          Set the statistics specified by the given xpath.
 void setStatsName(java.lang.String name)
          Sets the element name of the adapter.
 void setTimer(java.lang.Object timer_id, long delay_ms)
          Set a Timer event.
 void Start()
          Starts the adapter.
 void Stop()
          Stops the adapter.
 void Stop(long delay)
          Stops all the threads in the UnicastAdapter after a delay When stop returns, the adapter is stopped.
 void timerExpired(java.lang.Object Timer_Object)
          This function, a member of I_AdapterCallBack, is called for the WatchDogTimer timer and DelayNewKeyTimer.
 void updatePersonalKey(java.security.PrivateKey pKey)
          Update my private or personal key.
 
Methods inherited from class hypercast.NotificationHandler
addNotificationHandler, eventOccurred, handle_E2EACK_RECEIVED, handle_E2EPARTIALACK_RECEIVED, handle_MSG_WITH_E2EACK_SENT, handle_NAMING_EVENT, handle_NEWSTREAM_ARRIVED_EVENT, handle_NODE_ISSTABLE, handle_NODE_LEAVEGROUP, handle_NODE_LEAVEOVERLAY, handle_NODE_LOGICALADDRESSCHANGED, handler, removeNotificationHandler, stop, waitUntil_E2EACK_RECEIVED, waitUntil_E2EACK_RECEIVED, waitUntil_E2EPARTIALACK_RECEIVED, waitUntil_E2EPARTIALACK_RECEIVED, waitUntil_MSG_WITH_E2EACK_SENT, waitUntil_MSG_WITH_E2EACK_SENT, waitUntil_NAMING_EVENT, waitUntil_NAMING_EVENT, waitUntil_NEWSTREAM_ARRIVED_EVENT, waitUntil_NEWSTREAM_ARRIVED_EVENT, waitUntil_NODE_ISSTABLE, waitUntil_NODE_ISSTABLE, waitUntil_NODE_LEAVEGROUP, waitUntil_NODE_LEAVEGROUP, waitUntil_NODE_LEAVEOVERLAY, waitUntil_NODE_LEAVEOVERLAY, waitUntil_NODE_LOGICALADDRESSCHANGED, waitUntil_NODE_LOGICALADDRESSCHANGED, waitUntil_NODE_NEIGHBORHOODCHANGED, waitUntil_NODE_NEIGHBORHOODCHANGED
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SecurityProcessor

public SecurityProcessor(hypercast.HyperCastConfig c,
                         hypercast.KeyVault keyvault,
                         hypercast.I_UnicastAdapter _adapter)
Constructor.

Parameters:
c - overlay socket configuration object.
keyvault - a KeyVault instance.
_adapter - node adapter.
Method Detail

getKeyVault

public hypercast.KeyVault getKeyVault()
Gets the key vault object kept by this object.

Returns:
the key vault object.

getVersion

public java.lang.String getVersion()
Returns:
the current version information.

createAddressPair

public hypercast.I_AddressPair createAddressPair(hypercast.I_PhysicalAddress pa,
                                                 hypercast.I_LogicalAddress la)
Create an address pair from a physical address and a logical address.

Returns:
an address pair.

messageArrivedFromAdapter

public void messageArrivedFromAdapter(hypercast.I_Message a)
Checks all incoming protocol messages for security extensions and performs appropriate integrity checks and/or decryption before handing the message to the node to process. This function will also handle all security-related protocol messages.

Specified by:
messageArrivedFromAdapter in interface I_AdapterCallback
Parameters:
a - a message to be processed.
Throws:
java.lang.IllegalArgumentException - if the given message is not an instance of SecInfoExchange_Message.

initiateAuthentication

public void initiateAuthentication(hypercast.I_AddressPair src)
Initialize certificate exchange process with given node.

Parameters:
src - the logical address of the node with witch certificate is exchanged.

updatePersonalKey

public void updatePersonalKey(java.security.PrivateKey pKey)
Update my private or personal key. If the given private key is not null, use it to replace my private key; Otherwise, create a new personal key.

Parameters:
pKey - a private key.

restoreMessage

public hypercast.I_Message restoreMessage(byte[] receiveBuffer,
                                          int[] validBytesStart,
                                          int validBytesEnd)
Restore an SecInfoExchange_Message from byte array.

Specified by:
restoreMessage in interface I_AdapterCallback
Parameters:
receiveBuffer - the byte array buffer which contains the packet
validBytesStart - start position of valid section of the array
validBytesEnd - end of valid section of the array (actually, 1 beyond last valid byte.)
Returns:
null if buffer does not contain a complete message.
See Also:
I_AdapterCallback.restoreMessage(byte[], int[], int)

requestKeyFor

public void requestKeyFor(hypercast.I_LogicalAddress nodeLA)
Initiate a key exchange with a node

Parameters:
nodeLA - the logical address of the node with which the key is exchanged.

setLastSecureMessageTime

public void setLastSecureMessageTime(hypercast.I_LogicalAddress nodeLA)
Set the time when the last secure message was received from the given node.

Parameters:
nodeLA - the logical address of the node from which the secure message is received.

getAdapter

public hypercast.I_UnicastAdapter getAdapter()
Returns:
the adapter stored in the instance of this class.

getNode

public hypercast.I_Node getNode()
Returns:
the overlay node object stored in the instance of this class.

setAdapter

public void setAdapter(hypercast.I_UnicastAdapter adapter)
Sets the adapter stored in the instance of this class.

Parameters:
adapter - an I_UnicastAdapter object.

setNode

public void setNode(hypercast.I_Node node)
Sets the overlay node stored in the instance of this class.

Parameters:
node - an I_Node object.

getCallBack

public hypercast.I_AdapterCallback getCallBack()
Returns:
the adapter callback object stored in ths instance of this class.

timerExpired

public void timerExpired(java.lang.Object Timer_Object)
This function, a member of I_AdapterCallBack, is called for the WatchDogTimer timer and DelayNewKeyTimer. When a WatchDogTimer timer occurs, the node initiates a new key exchange with the problematic node. When a DelayNewKeyTimer timer occurs, the node check if key neighbor table is changed in the past NEW_KEY_DELAY mss. If there are changes, the node create new personal key and send it to all key neighbors.

Specified by:
timerExpired in interface I_AdapterCallback
Parameters:
Timer_Object - index of the timer that has expired

Start

public void Start()
Starts the adapter. It in turn starts the node adapter.

Specified by:
Start in interface I_UnicastAdapter
See Also:
I_UnicastAdapter.Start()

Stop

public void Stop()
Stops the adapter. It in turn stops the node adapter.

Specified by:
Stop in interface I_UnicastAdapter
See Also:
I_UnicastAdapter.Stop()

Stop

public void Stop(long delay)
Description copied from interface: I_UnicastAdapter
Stops all the threads in the UnicastAdapter after a delay When stop returns, the adapter is stopped. Any further calls (e.g. send, setTimer, clearTimer, etc.) will call an exception. Stop() may take a while to return. During that time, Callback functions may be called. Stop() will only return when all threads have returned from the Callback functions and are guaranteed never to enter a Callback function.

Specified by:
Stop in interface I_UnicastAdapter
Parameters:
delay - delay in milliseconds

close

public void close()
pass the close call down to the adapter.

Specified by:
close in interface I_UnicastAdapter

sendUnicastMessage

public void sendUnicastMessage(hypercast.I_NetworkAddress dst,
                               hypercast.I_Message msg)
Sends out an unicast message. It creates a secure message that wraps the plaintext protocol message and calls the same method in the node adapter to send the wraped message out..

Specified by:
sendUnicastMessage in interface I_UnicastAdapter
Parameters:
dst - the physical or underlay address of the destination of this message.
msg - plaintext protocol message to be sent out.
See Also:
(hypercast.I_PhysicalAddress, hypercast.I_Message)

sendMulticastMessage

public void sendMulticastMessage(hypercast.I_Message msg)
Sends out a multicast message. It in turn calls the same method in the node adapter.

Specified by:
sendMulticastMessage in interface I_MulticastAdapter
See Also:
I_MulticastAdapter.sendMulticastMessage(hypercast.I_Message)

createPhysicalAddress

public hypercast.I_PhysicalAddress createPhysicalAddress(byte[] byteaddr,
                                                         int offset)
Creates physical address from a byte array.

Specified by:
createPhysicalAddress in interface I_UnicastAdapter
Parameters:
byteaddr - an byte array containing a physical address.
offset - the position in byteAddr from where availabe data is read.
Returns:
a new instance of I_PhysicalAddress.
See Also:
I_UnicastAdapter.createPhysicalAddress(byte[], int)

createPhysicalAddress

public hypercast.I_PhysicalAddress createPhysicalAddress(java.lang.String addrString)
Creates physical address from a string.

Specified by:
createPhysicalAddress in interface I_UnicastAdapter
Parameters:
addrString - an string representing a physical address.
Returns:
a new instance of I_PhysicalAddress.
See Also:
I_UnicastAdapter.createPhysicalAddress(java.lang.String)

createPhysicalAddress

public hypercast.I_PhysicalAddress createPhysicalAddress()
Creates a new physical address.

Specified by:
createPhysicalAddress in interface I_UnicastAdapter
Returns:
a new instance of I_PhysicalAddress.
See Also:
I_UnicastAdapter.createPhysicalAddress()

getPhysicalAddressSize

public int getPhysicalAddressSize()
Returns the size of physical address, when carried in a packet, recognized by this adapter.

Specified by:
getPhysicalAddressSize in interface I_UnicastAdapter

createUnderlayAddress

public hypercast.I_UnderlayAddress createUnderlayAddress(byte[] byteAddressAndPort,
                                                         int offset)
Creates underlay address from a byte array of address - the inverse of toByteArray. The first 4 bytes reprsent the IP address, and the last 4 bytes represent the port number.

Specified by:
createUnderlayAddress in interface I_UnicastAdapter
Parameters:
byteAddressAndPort - an byte array containing a physical address
offset - the position in byteAddressAndPort from where availabe data is read.
Returns:
a new instance of I_UnderlayAddress
See Also:
INETv4OnePort.toByteArray()

createUnderlayAddress

public hypercast.I_UnderlayAddress createUnderlayAddress(java.lang.String addrString)
Creates underlay address object from a string.

Specified by:
createUnderlayAddress in interface I_UnicastAdapter
Parameters:
addrString - an string representing a physical address.
Returns:
a new instance of I_UnderlayAddress.

createUnderlayAddress

public hypercast.I_UnderlayAddress createUnderlayAddress()
Creates a new underlay address.

Specified by:
createUnderlayAddress in interface I_UnicastAdapter
Returns:
a new instance of I_UnderlayAddress.

getUnderlayAddressSize

public int getUnderlayAddressSize()
Returns the size of underlay address, when carried in a packet, recognized by this adapter.

Specified by:
getUnderlayAddressSize in interface I_UnicastAdapter

Reset

public boolean Reset(java.lang.Object socketObj)
Reset the sockets in the adapter. It in turn call the same method of the node adapter.

Specified by:
Reset in interface I_UnicastAdapter
Parameters:
socketObj - object passed to do reset.
See Also:
I_UnicastAdapter.Reset(java.lang.Object)

getInfo

public java.lang.Object getInfo()
Get information of the adapter. It in turn calls the same method in the node adapter.

Specified by:
getInfo in interface I_UnicastAdapter
See Also:
I_UnicastAdapter.getInfo()

setCallback

public void setCallback(hypercast.I_AdapterCallback adaptercallbackObj)
Set the adapter callback object.

Specified by:
setCallback in interface I_UnicastAdapter
See Also:
I_UnicastAdapter.setCallback(I_AdapterCallback)

getMyKeyFor

public javax.crypto.spec.SecretKeySpec getMyKeyFor(hypercast.I_AddressPair dst_ap,
                                                   hypercast.I_AddressPair src_ap)
The function return the key that the local node is exchanging with a remote destination node. When in NeighborhoodKey2 mode, the node might use different keys with different remote nodes.

Parameters:
dst_ap - the address of the remote node
src_ap - the address of the current node
Returns:
the key

getMyKeyTimestampFor

public long getMyKeyTimestampFor(hypercast.I_AddressPair dst_ap,
                                 hypercast.I_AddressPair src_ap)
See Also:
return the key timestamp for the key that is return by getMyKeyFor() function

setTimer

public void setTimer(java.lang.Object timer_id,
                     long delay_ms)
Set a Timer event.

. It calls the same method in the node adapter.

Specified by:
setTimer in interface I_UnicastAdapter
Parameters:
timer_id - a time event ID
delay_ms - a time in ms

setSecurityTimer

public void setSecurityTimer(java.lang.Object timer_id,
                             long delay_ms)
Set a SecurityTimer event

. It calls the same method in the node adapter.

Parameters:
timer_id - a time event ID
delay_ms - a time in ms

clearTimer

public void clearTimer(java.lang.Object timer_id)
Clear a Timer event

. It calls the same method in the node adapter.

Specified by:
clearTimer in interface I_UnicastAdapter
Parameters:
timer_id - a time event ID

clearSecurityTimer

public void clearSecurityTimer(java.lang.Object timer_id)
Clear a SecurityTimer event

. It calls the same method in the node adapter.

Parameters:
timer_id - a time event ID

getTimer

public long getTimer(java.lang.Object timer_id)
Get a Timer event

. It calls the same method in the node adapter.

Specified by:
getTimer in interface I_UnicastAdapter
Parameters:
timer_id - a time event ID
Returns:
time in ms

getSecurityTimer

public long getSecurityTimer(java.lang.Object timer_id)
Get a SecurityTimer event

. It calls the same method in the node adapter.

Parameters:
timer_id - a security time event ID
Returns:
time in ms
See Also:
I_UnicastAdapter.getCurrentTime()

getCurrentTime

public long getCurrentTime()
Gets the current time.

Specified by:
getCurrentTime in interface I_UnicastAdapter
Returns:
current time in ms.
See Also:
I_UnicastAdapter.getCurrentTime()

getMulticastAddress

public hypercast.I_PhysicalAddress getMulticastAddress()
Gets the multicast address of the adapter. It in turn the same method in the node adapter.

Specified by:
getMulticastAddress in interface I_MulticastAdapter
See Also:
I_MulticastAdapter.getMulticastAddress()

getStats

public org.w3c.dom.Element[] getStats(org.w3c.dom.Document doc,
                                      org.apache.xpath.XPath xpath)
                               throws HyperCastStatsException
Return the result of query for the statistics specified by the given xpath.

Specified by:
getStats in interface I_Stats
Parameters:
doc - Document used for create new elements or nodes.
xpath - XPath instance represents the statistics to be queried.
Throws:
HyperCastStatsException - If the xpath does not specify a valid subtree.
See Also:
I_Stats.getStats(org.w3c.dom.Document, org.apache.xpath.XPath)

setStats

public org.w3c.dom.Element[] setStats(org.w3c.dom.Document doc,
                                      org.apache.xpath.XPath xpath,
                                      org.w3c.dom.Element newValue)
                               throws HyperCastStatsException
Set the statistics specified by the given xpath. The value actually set is returned.

Specified by:
setStats in interface I_Stats
Parameters:
doc - Document used for create new elements or nodes.
xpath - XPath instance represents the statistics to be queried.
newValue - Element representing the value or sub-tree to be set.
Throws:
HyperCastStatsException - If the xpath does not specify a valid subtree or if any part of the the subtree is read-only, or if the newValue does not conform with the expected format.
See Also:
I_Stats.setStats(org.w3c.dom.Document, org.apache.xpath.XPath, org.w3c.dom.Element)

getReadSchema

public org.w3c.dom.Element[] getReadSchema(org.w3c.dom.Document doc,
                                           org.apache.xpath.XPath xpath)
                                    throws HyperCastStatsException
Return the schema element which represents the root of the sub-tree, specified by the given xpath, in read schema tree.

Specified by:
getReadSchema in interface I_Stats
Parameters:
doc - Document used for create new elements or nodes.
xpath - XPath instance representing the statistics which is the root of the sub-tree to be queried.
Throws:
HyperCastStatsException - If some part of the specified subtree does not correctly implement this interface method.
See Also:
I_Stats.getReadSchema(Document, XPath)

getWriteSchema

public org.w3c.dom.Element[] getWriteSchema(org.w3c.dom.Document doc,
                                            org.apache.xpath.XPath xpath)
                                     throws HyperCastStatsException
Return the schema element which represents the root of the sub-tree, specified by the given xpath, in write schema tree.

Specified by:
getWriteSchema in interface I_Stats
Parameters:
doc - Document used for create new elements or nodes.
xpath - XPath instance representing the statistics which is the root of the sub-tree to be queried.
Throws:
HyperCastStatsException - If some part of the specified subtree does not correctly implement this interface method.
See Also:
I_Stats.getWriteSchema(Document, XPath)

getStatsName

public java.lang.String getStatsName()
Gets the element name of the adapter. It in turn call the same method in the node adapter.

Specified by:
getStatsName in interface I_Stats
See Also:
I_Stats.getStatsName()

setStatsName

public void setStatsName(java.lang.String name)
Sets the element name of the adapter. It in turn call the same method in the node adapter.

Specified by:
setStatsName in interface I_Stats
Parameters:
name - the statistics name to be set.
See Also:
I_Stats.setStatsName(String)

handle_NODE_NEIGHBORHOODCHANGED

public void handle_NODE_NEIGHBORHOODCHANGED(hypercast.events.NODE_NEIGHBORHOODCHANGED event)
Handle neighborhood change event.

Overrides:
handle_NODE_NEIGHBORHOODCHANGED in class NotificationHandler