DRAFT

PostOffice Design Document

Approvals

Changelog

TABLE OF FIGURES

1. Purpose

This document is intended to provide the design guidelines for the Dream Park PostOffice network communication package.

2. Abbreviations

The following table is a list of abbreviations found within this documentation.

Table 2.1: Abbreviations

3. Requirements

3.1 PostOffice System Requirements

The purpose of the PostOffice system is to provide a standardized, secure, and reliable communications mechanism for a variety of applications. The concept itself was derived from the need to provide a communications system to a variety of dissimilar hardware devices that were not necessarily PCs. It was seen by the initial project that the PostOffice could be used to fill several other communications roles within the public sector, as well as to provide a solution to some communications needs within some of Random Logic's future applications.

The PostOffice system requirements are fairly straight forward and are outlined in Table 3.1. An explanation of each requirement follows the table.

Table 3.1: Post Office System Requirements

3.1.1 Free Licensing

All components of the PostOffice system will be freely distributable under a free license. The license chosen to meet this requirement is the GNU General Public License commonly known as the GPL. This application and all components thereof must conform to no more stringent licensing as that found under the GPL.

3.1.2 POSIX Compliance

In order to fit the widest range of platforms possible, the PostOffice will conform to POSIX specifications. This will provide a standard for both operation and coding of the application allowing it to be more easily ported to future platforms as well as providing easier maintenance of the application.

3.1.3 Generic Interface

The PostOffice system, being designed to fit into a variety of communications roles, will require a generic interface. Developers wishing to use this application to fulfill their communications needs will require a minimal amount of effort to interface their applications with the PostOffice. A well defined, generic interface will fill this need.

3.1.4 Extensible Protocol

While certain portions of the communications protocol used must remain standardized, there must be a mechanism to provide other protocols for situations not yet discovered. For this reason a communications protocol must be designed such that it can be extended as required by specific applications and also remain compliant with the standard protocol as used by the original PostOffice system.

3.1.5 Client/Server Model

The PostOffice is based upon a client/server model similar to that of many e-mail systems. The server portion of the system operates as a stand-alone application. The client portion operates on any devie that requires communication with other devices that are also running the PostOffice client. The server is the interface between clients.

3.1.6 Security

For applications requiring a secure method of communication, the PostOffice will provide option security software. This software, though not required for the normal operation of the system, will provide secure, strong encrypted, communication between clients. The security used will be such that no entity other than the intended recipient of a message will be able to read the message, including the PostOffice server or administrator.

3.1.7 Efficiency

Efficient communications can be a key component in many different applications. For this reason some effort must be given to provide the most efficient communications system possible while still meeting the other requirements of the PostOffice.

3.1.8 Reliability

Even more important that efficiency, reliability is a key component in communications. For this reason great emphasis is placed upon making the PostOffice system as reliable as possible with the goal of making it one of the most reliable communications systems available.

3.1.9 Standardized API

Both the client and server portions of the system will have a well defined and documented API. The APIs must be designed for the ease of use of developers in order to make the PostOffice desireable for use in their applications.

3.1.10 UDP and TCP Support

The system must support both UDP and TCP support for the widest variety of end-user applications support possible.

3.1.11 Multi-Threading

For systems that require high levels of performance, multi-threading should be designed into the PostOffice. Both the client and server portions of the system should include multi-threading support. In addition, this support should have the capability to be enabled or disabled by the end-user, if for no other reason than to support those systems that do not support threads.

3.2 Hardware Requirements

The hardware requirements for PostOffice are as follows:

• Any computer system capable of running a POSIX compliant UNIX operating system. Required for both the client machines and the server machine.

• A LAN or WAN connection.

• TBD MB Hard Drive space per system.

3.3 Software Requirements

The PostOffice will operate under the following operating systems and requires the following additional software:

• Red Hat Linux 7.1 or above for Pentium/Athlon

• Red Hat Linux 7.1 or above for DEC/Compaq Alpha

• GNU C/C++ compiler 2.96 or later (for building if needed)

• Socket++ 1.11 library

• OpenSSL TBD for optional security module

4. Post Office System Overview

The PostOffice (PO) is a generic communications wrapper written in C and C++. It is designed to be used in a variety of applications that require communication between multiple systems over a LAN and/or WAN. The PO supports both stream and data gram transports (TCP and UDP). The PO consists of two distinct yet similar parts, a client and a server.

4.1 The Post Office Server

The server listens for connections from clients and sets up communications with them. All clients communicate through the server. The PO server is responsible for routing messages between all connected clients. The PO server authenticates clients and, once authenticated, opens a two-way communication socket between the client and server. The client then tells the server which messages it wishes to receive. The server then checks each incoming message to determine which client(s) to route the message to. If there are no clients wanting to receive the message, the message is dropped (deleted from the server).

The authentication protocol includes optional facilities for security, server resetting, server disconnection and reconnection, and server status information.

4.2 The Post Office Client

The client subscribes to a server and a set of messages it wishes to receive. A client will request a connection from the server, and optionally authenticate itself to the server. Once connected, the client will send a list of message types it wishes to receive to the server. Once this list is sent, the client will listen for valid messages from the server. Some pre-defined message types will always be accepted by the client and will not be part of the list that is sent to the server. Examples of these messages are server connect/disconnect messages, server status, and server security messages.

5. PostOffice General Functional Description

The PostOffice system operates as a kind of mail transport agent in that it receives messages and routes them to appropriate locations. The PO is two distinct parts: a server and a client. The server is an application that receives messages from clients and routes them to other clients. The client is designed to interoperate with a parent application and send/receive messages for that application.

5.1 PostOffice Server Functional Description

Figure 5.1 shows a block diagram of the major parts of the PO server. A description of each part follows the diagram.

Figure 5.1: Server Functional Block Diagram

5.1.1 Server Status

The Server Status block keeps track of the status of various parts of the server. It is used to send status updates to the clients and administrator if/when required. In addition, it is used to perform some control functions such as socket initialization and reset, message queue control, authentication control, and security module control. A detailed explanation of all functions performed by this block can be found in Section 8.1.1.5. This block and all associated functionality is encompassed by the Server Status Thread.

5.1.2 Authentication

The Authentication block handles client authentication. Authentication messages are routed to/from this block and through the Security Module if used. A detailed description of this block and client authentication can be found in Section 8.1.1.2. This block and all associated functionality is encompassed by the Handshaking Thread.

5.1.3 Routing Control

Routing Control handles all message routing. Data extracted from the headers of incoming messages is used by this block to determine where a message is to be sent and message priority. High priority server messages are routed directly to the Server Status block where they are handled immediately. Authentication messages are routed to the Authentication block for processing there. Other messages are placed into the Message Queue to await sending or further processing by the server.

Routing Control is also responsible for formatting messages from the server. High priority (outgoing) server messages are sent immediately to the PO Send block for sending. Lower priority messages are placed into the Message Queue for sending later as determined by the Message Queue block.

A detailed description of this block can be found in Section 8.1.1.4. This block and all associated functionality is encompassed by the Message Dispatch Thread.

5.1.4 Message Queue

All messages, with the exception of very high priority messages, are placed into the Message Queue. The Message Queue is a combination FIFO buffer and a priority sorted buffer. Messages are sorted in the buffer first by priority and then by the message timestamp. In this manner the oldest and highest priority messages are sent first. A detailed description of this block can be found in Section 8.1.1.4. This block and all associated functionality is encompassed by the Message Dispatch Thread.

5.1.5 Extract Message

This block extracts header data for use by Routing Control. In addition, it is used to extract the message contents for messages directed to the server itself. If the Security Module is used, it interfaces with that module in order to decrypt the encrypted message and/or header contents.

A detailed description of this block can be found in Section 8.1.1.4. This block and all associated functionality is encompassed by the Message Receive Thread.

5.1.6 Format Message

This block formats messages, including headers, that are to be sent from the server to one or more clients. Low priority messages are formatted and sent to Routing Control for insertion into the Message Queue. High priority messages are formatted and sent directly to the PO Send block for sending. If the optional Security Module is used, it interfaces with that module to encrypt messages and/or headers before sending or forwarding to Routing Control.

A detailed description of this block can be found in Section 8.1.1.5. This block and all associated functionality is encompassed by the Server Status Thread.

5.1.7 Security Module

This block is optional. This block comprises encryption and decryption software and a key database. It is used to encrypt and decrypt messages based upon a public/private key system. It is also used to handle server key maintenance and authentication. A detailed description of this block can be found in Section 8.1.4. This block includes code sections that are used by all threads comprising the PO server.

5.1.8 PO Receive

This block handles all incoming communications from clients. It performs all input socket operations with all connected clients. A detailed description of this block can be found in Section 8.1.1.3. This block and all associated functionality is encompassed by the Message Receive Thread.

5.1.9 PO Send

This block handles all outgoing communications to clients. It performs all output socket operations with all connected clients. A detailed description of this block can be found in Section 8.1.1.4. This block and all associated functionality is encompassed by the Message Dispatch Thread.

5.2 Post Office Client Function al Description

Figure 5.2 on the following page shows a block diagram of the major parts of the PO client. A description of each part follows the diagram.

Figure 5.2: Client Functional Block Diagram

5.2.1 Parent Application

This is not part of the client, but is some parent application that uses the client for communication. The Parent Application uses the API defined in Section 8.2.2 of this document to interoperate with the PO client.

5.2.2 Server Handshaking

6. Post Office Server Detailed Functional Description

PO Server functional description.

7. Post Office Client Detailed Functional Description

PO Client functional description.

8. Software Design

8.1 The Server

8.1.1 Server Threads

The following threads make up the PO server:

1. Main thread

2. Handshaking thread

3. Message receive thread

4. Message dispatch thread

5. Status Thread

In the case of a PO system operating as a single threaded application, each of the above threads will operate as a software module within a single process. In such a case the PO system will operate within a loop with each module executed according to the amount of data that an individual module needs to process. More details regarding single threaded operation can be found in Section 8.1.2.

8.1.1.1 Main Thread Operation

This thread performs initial server initialization. Part of this initialization involves starting several child threads, the Handshaking, Message Receive, Message Dispatch, and Status threads. After initializing the server and starting the child threads, it opens a socket and listens for connection requests from clients. When a connection is requested, the Main Thread initiates communication with the requesting client, and then hands the client over to the Handshaking Thread, returning back to listen for further connections.

8.1.1.2 Handshaking Thread Operation

The Handshaking Thread is responsible for client authentication. If the optional security module is used, this thread performs all security authentication. Once a client is authenticated, it is given a port number to use for further communication. The client then sends its subscription list, which the Handshaking Thread accepts and sends to the Status Thread for insertion into the server Subscription List. The client then disconnects, and reconnects to the new port. Once the client is reconnected, the Handshaking Thread processes the next client, leaving the previous client to be handled by the Message Receive and Message Dispatch threads.

8.1.1.3 Message Receive Thread Operation

The Message Receive Thread parses all client sockets for incoming packets in a round-robin fashion. When a message is detected, it is read and verified. The verification process includes determining the Message Type from the Header, verifying the Checksum if used, and placing the message in the Message Queue. In the case of high priority messages, the Message Dispatch Thread is notified of the message and the header information is passed to it.

8.1.1.4 Message Dispatch Thread Operation

The Message Dispatch Thread reads messages from the Message Queue and using the Subscription List routes them to the various clients. The Dispatch Thread flowchart is illustrated in Figures 8.1.1.4-1 to 8.1.1.4-3.

Figure 8.1.1.4-1: Message Dispatch Thread

Figure 8.1.1.4-2: Message Dispatch Thread (continued)

8.1.1.5 Status Thread Operation

The Status Thread monitors client connection status, server status, security status, and maintains the Subscription List located in the Routing Module. It keeps track of available ports and sockets, and updates the Subscription List when a client connects or disconnects. It also creates the various server status messages and log messages and is responsible for routing the status messages to the clients. This thread is also used to control the operation of the server such as resetting and restarting it.

8.1.2 Single Threaded Operation

8.1.3 PostOffice Subscription List

The subscription list is used to route messages to the connected clients. The list contains all valid message types. Each message type in the list has a list of clients associated with it that will receive that message. Messages that are to be routed to all clients are not part of the list and are routed separately from all other messages. The list has the following format:

8.1.4 Optional Security Module

8.2 The Client

8.2.1Client Threads

8.2.2 Client API

8.3 Objects Common To Both Client and Server

8.3.1 The Message Class

All messages are composed of three parts: the Header, the Data, and the Footer. The Header is pre-defined for all message formats. The Data varies with the message format and may be defined as required by the application. In order to support the basic communication protocol, there are some pre-defined Data formats as shown in TBD. The Footer may contain a 32-bit checksum of the Data as defined by the application and the pre-defined message formats, or other data, or nothing.

8.3.1.1 Standard Message Format

The standard message format is defined in the following table and sub-sections. While the message itself will vary in length, and the Header and Footer are of fixed length. In addition, all messages are limited to a maximum length, including Header and Footer, of 1038 bytes.

Table 8.2.1.1 - Standard Message Format

8.3.1.1.1 Version Byte

The version byte is used to synchronize the message format between systems. At this time there are only two versions indicated by 0x00 or 0x01 in this field. A version byte of 0x00 indicates a standard message format in clear text. A version byte of 0x01 indicates an encrypted message payload. See Sections TBD for more information about the optional security module.

8.3.1.1.2 Message Type

The message type is used to route the message to the appropriate clients. The message type contains 4 fields of one byte each. The fields are, from MSB to LSB, Group, Category, Event Type, and Event. Messages can be sorted according to these fields. Each Event is a member of a unique Event Type. Each Event Type is in turn a member of a unique Category. Each Category is a member of a unique Group. The PO specification allows for messages to have most of these fields defined by the user for the target application. There are some specifically defined messages and associated fields in order to provide the minimum required PO functionality. These are defined in the following tables, Table 8.2.1.1.2-1 - TBD. For descriptions of the various message formats, see TBD.

Table 8.2.1.1.2-1 Pre-defined Post Office Groups

Table 8.2.1.1.2-2 Pre-defined Post Office Categories

Table 8.2.1.1.2-3 Pre-Defined Post Office Event Types

Table 8.2.1.1.2 -4 Pre-defined Post Office Events

8.3.1.1.3 Priority

The Priority field determines which messages have precedence over other messages. It is used as a means of routing critical and time sensitive messages to clients as soon as possible. Priority may be assigned in any fashion, but pre-defined message types also have pre-defined priorities as defined in TBD. In the event that multiple messages share the same priority and message type, those messages will be routed according to the order in which they were received. For further routing order information, see TBD.

8.3.1.1.4 Source ID

The Source ID field contains a unique ID designating the client that sent the message. The ID 0x0000 is reserved for the Post Office server. IDs are assigned by the server as part of the connection and authentication process. The server keeps track of IDs and may recycle those that are no longer in use - e.g. when a client disconnects its ID may be used by a new client.

8.3.1.1.5 Payload Size

The Payload Size indicates the number of bytes contained in the actual message (the Data), not including the Header and Footer. The Payload Size is used to determine how much storage to allocate for the message, how many bytes to read from the Message Queue, and for Data validation along with the Checksum. The maximum Payload Size is TBD and the minimum is zero.

8.3.1.1.6 Payload

The Payload field is the actual contents of the message, if any. The Payload can be of any format as defined by the application, but there are some pre-defined formats associated with the pre-defined Message Types. The Payload length in bytes is equal to the number contained in the Payload Size field, and not more than 1024 bytes.

8.3.1.1.7 Checksum

The Checksum is a 4 byte field containing a 32-bit checksum of the Data in the Payload field. The Checksum is optional for application defined messages, and is not used with some pre-defined messages. The checksum is defined as the 32-bit sum of the 8-bit data contained in each byte of the Payload.

8.3.1.2 Pre-defined Message Definitions

This section describes all pre-defined message types in detail. Table 8.2.1.2-1 shows the structure of all pre-defined messages. Note that the Source ID field is not shown in order to preserve space. The Source ID is the ID of the client or server sending the message, and is determined by the server. See section TBD for more information on the Source ID field. For further details of each message and the data fields each contains, see the subsequent paragraphs.

Table 8.2.1.2-1: Pre-defined Message Structure

8.3.1.2.1 Server Offline

The Server Offline message is sent to any clients attempting to connect to the PO or sending a Query Status. The Payload contents are the time the server went offline (Offline Time) and are in Julian seconds, GMT. The Payload Size is 4 bytes for the Offline Time and the Checksum is used.

8.3.1.2.2 Server Resetting

The Server Resetting message is sent to all connected clients when the PO is getting prepared to reset. The Payload contains the time it will disconnect (Offline Time) and the estimated time it will return online (Time Online). The Offline and Online times are in Julian seconds, GMT. The Payload Size is 8 bytes for the Offline Time and the Online Time and the Checksum is used.

8.3.1.2.3 Server Unavailable

The Server Unavailable message is sent to any clients attempting to connect or sending a Query Status message to the PO when it is to be unavailable for an undetermined amount of time. The Payload contents are the time it became unavailable (Time Offline) and an estimated time of return (Time Online). The Time Online is only an estimate and may change from one message to the next. The Offline and Online times are in Julian seconds, GMT. The Payload Size is 8 bytes for the Offline Time and the Online Time and the Checksum is used.

8.3.1.2.4 Security Compromised

The Security Compromised message is sent to all connected clients if the security of the server has been detected as compromised, and if the security option is in use. The Payload contents are the time that the compromise was detected by the server (Time Detected) and a Security Code indicating the nature of the compromise. The Time Detected is in Julian seconds, GMT. The Payload Size is 5 bytes for the Time Detected and the Security Code, 4 bytes for the time and 1 byte for the code, and the Checksum is used.

8.3.1.2.5 Authentication Request

The Authentication Request message is sent to all clients by the PO to request that each client verify itself. The Payload content is the time of the request (Time) in Julian seconds, GMT. The Payload Size is 4 bytes for the Time and the Checksum is used.

8.3.1.2.6 Server Available

8.3.1.2.7 Connection Grant

8.3.1.2.8 Connection Request

8.3.1.2.9 Subscription List

8.3.1.2.10 Client Disconnecting

9.

10.

10.1 Global Data Types

Table 7.1: Global Data Types

11. File Formats

12. Debugging and testing