Home Automation, Inc. HAI Network Communication Protocol Description This document contains the intellectual property of Home Automation, Inc. (HAI). HAI authorizes the use of this information for the sole purpose of developing software and systems to work with HAI's Network Interface. The specifications in this document are subject to change without notice. Document Number 20P09-1 Rev A May 2003
1. Introduction This document describes the protocol used to communicate between a client device (personal computer, etc.) and an HAI OmniPro II controller using the controller s Ethernet network interface. The HAI network communication protocol uses standard Ethernet, IP (Internet Protocol) and UDP (User Datagram Protocol) protocol layers to transport HAI application-level packets across the network. The use of standard transport and routing protocols enables HAI OmniPro II controllers to be used in any standard network environment. The network environment may range from a small local area network (LAN) in a single residence to the worldwide Internet. Refer to the attached diagrams for related details while reading the remainder of this document. 2. Protocol Description The HAI OmniPro II controller connects to the network via a standard Ethernet interface. The controller listens for all IP/UDP communications addressed to it on a specific UDP port number. The controller tracks the state of different client sessions by the unique combination of the source IP address (from the IP header) and the source port (from the UDP header) of the client. The Ethernet Frame, IP Header and UDP Header merely provide the standardized information required by the network infrastructure (routers, etc.) to transport HAI packets between client and controller. The actual controller transaction requests and responses are contained in the HAI packet. The structure and interpretation of the HAI packet is described in the following paragraphs. The first field of the HAI application packet is a 16-bit message sequence number, transmitted mostsignificant-byte first. This field provides a mechanism for detecting duplicate packets and dynamically adjusting network timeout periods to accommodate varying network delays. If the value is set to zero, sequence tracking is disabled for the packet. If sequence tracking is used, the client increments this value each time it sends a packet to the controller. Note that since a sequence number of zero has special significance, the sequence number value rolls over from 65535 to one instead of zero. The controller replies to client requests using the same message sequence number assigned by the client. The next field is the 8-bit message type. This value defines the nature of the message, so that it can be processed accordingly. The next 8-bit field is reserved for future use. And, finally, the message data field comprises any data or message associated with the specified message type. This field may be empty. This is the only field that is ever encrypted. Page 1
When the controller receives a HAI packet, it examines the message type field, and takes the appropriate action as defined by the following rules. If the controller receives a packet that is not a valid HAI packet (i.e., missing or invalid message type ), the controller quietly discards the packet without a reply. If the message type is Client request new session : If the controller cannot initiate a new session (i.e., too many sessions already open, etc.), it replies to the client with a Controller cannot start new session message, and no further action is taken; otherwise If the controller already has a session open for this client, that session is quietly terminated (i.e., no termination message is sent to the client), and a new session is initialized as described below. The controller initiates a new session associated with this unique client. The controller uses a random number generator to produce a 40-bit session ID. The session ID will be used by both client and controller to modify the private encryption key, which is known to both, resulting in a key that is unique for this session. The controller replies to the client with a Controller acknowledge new session message. The message data consists of a 16-bit value that indicates the HAI network protocol version being used by the controller, followed by the 40-bit session ID, both transmitted most-significant-byte first. The controller generates the unique encryption key for this session and initializes the encryption/decryption algorithms. The 128-bit session key is computed as follows: a) the 88 most significant bits of the session key are identical to the corresponding bits of the private key. b) the 40 least significant bits of the session key are the result of a logical XOR of the 40 least significant bits of the private key and the 40 bits of the session ID. Page 2
If the message type is Client request secure connection : If the controller does not already have an active session for the client, it replies to the client with a Controller session terminated message, and no further action is taken; otherwise a) The controller decrypts the message data, which should consist of the 40-bit session ID (transmitted MSB first). b) The controller compares the session ID received from the client to the session ID previously generated by the controller. c) If the session IDs are identical, this confirms that the client received the session ID intact, and used it to produce the correct session encryption key. The controller responds with the Acknowledge secure connection message, with the session ID in the data field. d) If the session IDs are NOT identical, the controller replies with the Controller session terminated message, and terminates the session. If the message type is Omni-Link message : If the controller does not already have an active session for the client, it replies to the client with a Controller session terminated message, and no further action is taken; otherwise The controller decrypts the message data, and treats it as a standard Omni-Link message. If the Omni-Link message requires a reply, the controller encrypts the standard Omni-Link reply message and replies to the client with a message type of Omni-Link message and the encrypted message in the data field. If the message type is Client session terminated : The controller replies with the Controller session terminated message and, if a session is active, terminates the session. Page 3
3. Encryption As mentioned above, certain message types require encryption or decryption of the message data portion of the HAI application packet. This section describes the encryption/decryption methods. Encryption and decryption of data in the HAI application packet is based on the Advanced Encryption Standard (AES) using a 128-bit cryptographic key. The AES (sometimes referred to as the Rijndael algorithm, derived from the names of the developers) was selected by the National Institute of Standards and Technology (NIST) and approved by the U.S. Department of Commerce (in May, 2002) as a robust replacement for the widely-used, but aging and vulnerable, DES encryption standard. The AES algorithm is a symmetric block cipher that is capable of using cryptographic keys of 128, 192 or 256 bits to encrypt and decrypt data in blocks of 128 bits. Further information about the AES can be found at the following NIST website: http://csrc.nist.gov/cryptotoolkit/aes and in the Federal Information and Processing Standards (FIPS) publication FIPS-197. The following procedure is used to encrypt HAI message data: 1. Process data in 128-bit (16-byte) blocks. If available data does not fill a 16-byte block, the data is left-justified and padded on the right with zeros to fill the block. 2. Modify the first two bytes of the 16-byte encryption block by performing a logical XOR operation with the two bytes of the message sequence number in the HAI header (i.e., XOR the first byte of the encryption block with the MSB of the message sequence number, and XOR the second byte of the encryption block with the LSB of the message sequence number). 3. Encrypt the 16-byte block using the AES encryption algorithm and the 128-bit session key that was negotiated when the client and controller established the secure connection. 4. Process the next block of data until all data has been processed. A similar procedure is used to decrypt HAI message data: 1. Process data in 128-bit (16-byte) blocks. 2. Decrypt the 16-byte block using the AES decryption algorithm and the 128-bit session key that was negotiated when the client and controller established the secure connection. Page 4
3. Modify the first two bytes of the 16-byte encryption block by performing a logical XOR operation with the two bytes of the message sequence number in the HAI header (i.e., XOR the first byte of the encryption block with the MSB of the message sequence number, and XOR the second byte of the encryption block with the LSB of the message sequence number). 4. Process the next block of data until all data has been processed. 5. If the number of bytes in the original message (prior to encryption) was not an exact multiple of 16, the decrypted message will have one or more trailing pad bytes. The length of the actual message (not including the pad bytes) should be determined by examining the message length field of the Omni-Link message. Page 5
HAI Network Communication Protocol Typical Ethernet II Frame with Embedded IP, UDP and HAI Application Packets 16 bits Ethernet Frame Ethernet Destination MAC Address (bits 47-32) Ethernet Destination MAC Address (bits 31-16) Ethernet Destination MAC Address (bits 15-0) Ethernet Source MAC Address (bits 47-32) Ethernet Source MAC Address (bits 31-16) Ethernet Source MAC Address (bits 15-0) Ethernet Type Code (IP = 0x0800) Ethernet Frame Header IP Packet IP Version Flags IP Header Length IP Type of Service Total IP Packet Length (in bytes) Identification Fragment Offset Time to Live IP Header Checksum Protocol IP Header UDP Packet HAI Packet IP Source Address (bits 31-16) IP Source Address (bits 15-0) IP Destination Address (bits 31-16) IP Destination Address (bits 15-0) UDP Source Port UDP Destination Port UDP Length UDP Checksum HAI Message Sequence Number HAI MessageType HAI Reserved = 0x00 UDP Header HAI Application Header HAI Application Data (variable length, if any) HAI Application Data Ethernet Checksum (bits 31-16) Ethernet Checksum (bits 15-0) Ethernet Frame Trailer Page 6
HAI Network Communication Protocol HAI Application Packet Format The following table describes the format of the HAI application data that is transmitted within the user data (payload) area of an IP/UDP packet. Size (bytes) Description Comments 2 Message sequence number 0 = Sequence tracking disabled 1..65535 = Sequence number of this packet (byte order is MSB..LSB) 1 Message type 0 = No message 1 = Client request new session 2 = Controller acknowledge new session 3 = Client request secure connection 4 = Controller acknowledge secure connection 5 = Client session terminated 6 = Controller session terminated 7 = Controller cannot start new session 16 = Omni-Link message 1 Reserved 0 = unused variabl e Message data May be empty, depending on message type Page 7
HAI Network Communication Protocol Typical Message Sequence Sequence Number Encrypted Client Direction Controller 1 No Request new session 1 No 2 Yes Request secure connection - session ID 2 Yes 3 Yes Omni-Link log-in request 3 Yes Yes Omni-Link message Acknowledge new session - protocol version - session ID (40- bit random data generated by controller) Acknowledge secure connection - session ID Omni-Link log-in acknowledge Yes Omni-Link reply Yes Omni-Link log-out Yes No No Client session terminated Omni-Link log-out acknowledge Controller session terminated (timed out, terminated by client, etc.) Page 8