IDA Authenticated Communication Protocol (IACP) Last modified: November 20, 2008
The IDA Authenticated Communication Protocol (IACP) is a TCP/IP based protocol designed for communication between IDA seismic stations, data collection hubs, and TCP/IP enabled digitizers. It allows for, but does not require, the inclusion of digital signatures for authentication of frame contents. The design is meant to be simple and sufficiently general that it can be used for both data communication as well as command and control applications. It is easily extensible to allow for support of new data formats and TCP/IP aware digitizers.
The IDA System Interface (ISI) Toolkit is a C language implementation of the formats and protocols described in this document. Client side source code is available for pickup at
ftp://idahub.ucsd.edu/pub/pickup/ISI_Toolkit.tgz
IACP communication is done via the exchange of variable length frames over a TCP/IP socket. These frames consist of a 16-byte preamble, followed by a variable length payload, followed by an optional digital signature. The basic frame format follows.
| 0 | 1 | 2 | 3 |
--------------------------------------------------------------------+
0 Signature ('IACP')
--------------------------------------------------------------------+
4 Frame sequence number (unsigned 32-bit integer, NBO)
--------------------------------------------------------------------+
8 Payload identifier (unsigned 32-bit integer, NBO)
--------------------------------------------------------------------+
12 Payload length, N (unsigned 32-bit integer, NBO) --------------------------------------------------------------------+ 16 N bytes of payload --------------------------------------------------------------------+ 16+N Authentication Key Identifier (unsigned 32-bit integer, NBO)
--------------------------------------------------------------------+
20+N Authentication size, M (unsigned 32-bit integer, NBO) --------------------------------------------------------------------+ 24+N+M M bytes of authentication data --------------------------------------------------------------------+
Frame Signature
The 4-byte signature appears at offset 0, and is for IACP frame identification. It is useful for locating IACP frames while snooping the network, and for rejecting casual port probes.
Frame Sequence number
The frame sequence number is inherited from the CD1.1 specification, which requires a unique "serial number" for each frame ever sent from a particular frame creator. It was useful as a debugging aid during initial development, but is no longer used in the current IACP implementation. It has been retained only for compatibility with deployed systems.
Payload Identifier
The payload identifier is an assigned number that uniquely identifies the type of payload to follow. Identifier values 0 through 1999 have been assigned or otherwise reserved. Identifier values 2000 through 4,294,967,296 are available upon request.
Identifiers 1 through 99 are reserved for the IACP handshake. Identifier 1 is used for the IACP handshake frame:
#define IACP_TYPE_HANDSHAKE 1 /* handshake */
Identifier values 100-999 are for reserved IACP I/O control (post-handshake). Of these, the following control frames have been defined:
#define IACP_TYPE_ALERT 100 /* peer disconnect notification */
#define IACP_TYPE_NOP 101 /* i/o heartbeat */
#define IACP_TYPE_ENOSUCH 102 /* rejected frame notification */
Identifier 0 is the IACP “null” frame, and is used to send breaks to the peer process.
#define IACP_TYPE_NULL 0 /* break */
All other identifier values are of interest only to the various applications that use IACP as the underlying protocol. For example, identifier values 1000 through 1999 are reserved for use by the IDA System Interface (described in a companion document).
Payload Length
This is simply the number of bytes to follow. Zero is a valid length, in which case the payload identifier is itself the message.
IACP Payload
The IACP payload consists of a block of data. All frames with payloads in the range 0- 999 contain information related to the IACP session, and are interpreted and acted on by the IACP client or server. The contents of all other frames are opaque to IACP and are passed to the user application.
Authentication Key Identifier
The 4-byte authentication key identifier is the identifier of the certificate with the public key required to verify the digital signature. This is the convention used by CTBTO CD1.1.
Authentication size
The authentication size is the number of bytes of authentication data to follow. If the frame is not signed then this field would be zero.
Authentication data
This is the digital signature.
The IACP handshake frame is a frame with a payload identifier of 1. The format of the IACP handshake frame payload consists of 0 or more subframes that are used to define the connection attributes (timeout interval, buffer lengths, etc). The format of these subframes consists of (length, identifier, value) triples as follows:
| 0 | 1 | 2 | 3 | --------------------------------------------------------------------+ 0 Item identifier (unsigned 32-bit integer, NBO) --------------------------------------------------------------------+ 4 Item length, N (unsigned 32-bit integer, NBO) --------------------------------------------------------------------+ 8 N bytes of data --------------------------------------------------------------------+
The concatenation of these subframes constitutes the payload of the IACP handshake frame. The following handshake subframe identifiers are presently defined:
#define IACP_TYPE_PID 2 /* peer process id */ #define IACP_TYPE_TO 3 /* i/o timeout */ #define IACP_TYPE_SNDSIZ 4 /* TCP/IP send buffer len */ #define IACP_TYPE_RCVSIZ 5 /* TCP/IP receive buffer len */
The value field for each of these 4 items is also an unsigned 32-bit integer, however the format allows for the definition of new items which have some other size and type.
Peer process id
The peer process id is tagged with an item identifier of 2 (IACP_TYPE_PID). The peer process id is not required for IACP dialogs to take place, but is sent as a "courtesy" to the peer process. Including the process id of the peer in log messages has been a convenient debugging aid.
I/O timeout interval
The I/O timeout interval is tagged with an item identifier of 3 (IACP_TYPE_TO). The I/O timeout interval is the number of milliseconds to allow for network reads and writes to complete.
TCP/IP Send and Receive buffer lengths
The TCP/IP send buffer length is tagged with an item identifier of 4 (IACP_TYPE_SNDSIZ), while the TCP/IP receive buffer length is tagged with an item identifier of 5 (IACP_TYPE_RCVSIZ). The buffer lengths are given in bytes. A value of 0 is interpreted to mean that the default TCP/IP buffer length, as defined by the underlying operating system, is to be used. Normally that will always be the case, however, this option is provided as it can sometimes aid in improving throughput over certain types of circuits.
The IACP heartbeat frame can be sent by either side of the connection, but is normally only sent only by the server. The heartbeat frame is an IACP frame with a zero length payload and a payload identifier of 101 (IACP_TYPE_NOP).
IACP alert frames are sent by the peer immediately prior to terminating the connection. The payload is an unsigned 32-bit integer in network byte order that describes reason for the disconnect. The following cause codes are currently defined:
#define IACP_ALERT_NONE 0 /* never sent */ #define IACP_ALERT_DISCONNECT 1 /* normal disconnect */ #define IACP_ALERT_REQUEST_COMPLETE 2 /* request complete */ #define IACP_ALERT_IO_ERROR 3 /* i/o error */ #define IACP_ALERT_SERVER_FAULT 4 /* server error */ #define IACP_ALERT_SERVER_BUSY 5 /* too many active connections */ #define IACP_ALERT_FAILED_AUTH 6 /* invalid frame signature */ #define IACP_ALERT_ACCESS_DENIED 7 /* access to server refused */ #define IACP_ALERT_REQUEST_DENIED 8 /* client request refused */ #define IACP_ALERT_SHUTDOWN 9 /* shutdown in progress */ #define IACP_ALERT_PROTOCOL_ERROR 10 /* illegal frame received */ #define IACP_ALERT_ILLEGAL_DATA 11 /* unexpected frame data */ #define IACP_ALERT_UNSUPPORTED 12 /* unsupported IACP frame type */ #define IACP_ALERT_OTHER_ERROR 99 /* other error */
The IACP null frame is a frame with a zero length payload and a payload identifier of 0 (IACP_TYPE_NULL). It is used to indicate the end of a sequence of frames.
IACP sessions are done
in a client-server fashion. The client establishes a TCP/IP socket
connection with a server process listening at some known port. The
port number commonly used for IDA IACP servers is 39136, an
arbitrary value.
After
the connection is established, the client sends an IACP handshake
frame (payload identifier 1) that suggests desired connection
attributes to the server. The server replies to the IACP handshake
frame with its own handshake frame that describes the actual
attributes which will be used during the session.
Among the connection
attributes is the timeout interval, specified in milliseconds. If no
traffic occurs during this interval then each side should declare the
connection lost and disconnect. The server is guaranteed to send IACP
heartbeat frames (payload identifier 101) at half this interval so
some traffic should always be present over a healthy connection.
After the handshake
frames have been exchanged, the server waits for commands from the
client. IACP commands and responses are frames whose payload
identifiers are mutually recognized by both the client and server.
Normally these commands will generate a response from the server to
the client, but the protocol does not explicitly require this. While
the server is waiting for commands from the client, or waiting to
generate or send responses, it must also ensure that heartbeats are
sent at appropriate intervals, if required to maintain the
connection.
How
long a connection is maintained is implementation dependent. The
server may chose to break the connection after it has received and
processed a single request from the client, or it may chose to wait
for a new request from the client after it is done with the current
request. In any event, if the server detects an I/O error, or
encounters an internal error, then it will break the connection. IACP
alert frames should be sent by the peer when it has decided to
terminate the connection, and its payload includes a code that gives
the reason for the disconnect. The protocol does not require
the use of IACP alert frames, and it is acceptable for either end to
simply close its socket without notification. The use of IACP alert
frames in initiating disconnects is only to aid in distinguishing
between normal disconnects and those due to other problems with the
peer. It is up to the client to decide how to respond to a
disconnect from the server.
If the client sends a command frame that the server does not recognize, the server will respond with a “no such frame” message. This is an IACP frame with payload identifier 102. It is up to the client to decide the appropriate response to this reject.