       Copyright (c) 2001  Elron Software Inc.   All rights reserved.

Message Provider Socket API

The Message Provider (MP) Socket API is a socket-based interface which enables client applications to send email documents to a Message Inspector Service Provider (MISP) application for analysis, and get back the results of that analysis. The MISP application implements a Message Server, which handles messages sent to it by the clients. Each client must in turn implement a Results Server, to handle the analysis results messages which will be sent back to it by the MISP. Results will not necessarily come back in the same order that the message requests were sent, so the client application must keep track of its active sessions, and use the Session IDs to match them to results messages.

Each message (whether for a Message Server or a Results Server) gets a response right away, on the same connection, which tells the sender the status of the message tranmission. If a response has any status value other than 0 (OKAY), it indicates that something is wrong, either with the network or with the sending or receiving application. Every transmission, whether a message or a response, starts with the 32-bit byte count (in network byte order) of the remainder of the transmission.

The Message Server protocol defines three message types:

MPAnnounceClient: This allows a client to make its presence known to the Message Server. This also gives the client a chance to tell the Message Server what port the client's Results Server will be listening on.
MPBeginSession: This passes information about the email document (sender, recipients, etc) which allows Message Inspector to quickly decide, based on the policy settings, whether the email document needs further analysis. Its response contains a Session ID which should be used later on to match up the MPResults message. If Message Inspector decides it wants to analyze the email document, the matching MPResults message will have an action value of 3 (INSPECT_DATA). Otherwise the action will have a value of 0 (for PASS) or 1 (for BLOCK), and the Session ID for that message will become invalid.
MPSessionData: If the MPResults message that came back for an MPBeginSession message had an action value of 3 (INSPECT_DATA), the client should follow it up with an MPSessionData message. This is to provide Message Inspector with the content (in RFC-822 format) for the email document, so it can analyze it. If the MPResults message that came back for the MPSessionData message had an action value of 2 (REPLACE_DATA), that MPResults message will also contain email document data which should be used to replace that in the original email document before PASSing it. If it had a value of 5 (CLONE_DATA), that MPResults message will contain data for 2 or more emails which should replace the original email (see the section on the MPResults message for more on this).
MPSessionCancel: If the MPResults message that came back for an MPBeginSession message had an action value of 3 (INSPECT_DATA), but the message data is greater than the maximum allowed, the client should follow it up with an MPSessionCancel message. This tells Message Inspector that this document will not be analyzed after all.

The Results Server protocol defines two message types:

MPSettings: This message is sent from the Message Server to initialize or update the client application's system settings.
MPResults: This message is sent from the Message Inspector application to the Results Server implemented by a client application. It gives that client application the results from analyzing either an MPBeginSession message or an MPSessionData message. The Session ID value in the message is used to match these results with the corresponding open session in that client. If the response is to an MPSessionData message, and the action value is REPLACE_DATA, the results message will also contain the replacement data for that email document. There is a special case that may arise when a message has more than one recipient in its TO list: the Message Inspector application may define different policies for these recipients which demand different actions for the message they share. In these cases, the original message is replaced by new messages, one for each set of recipients which share a common policy. The MPResults message will then have an action value of CLONED_DATA, followed by a clone count. This is followed by a series of blocks (one for each clone), each of which contains the envelope information, followed by the rfc822 data (the header + CRNL + the body).

Here is a detailed description of the protocol and data format used for these servers. Please note that all data elements larger than a byte must be transmitted in network byte order.

Message Server API

MPAnnounceClient message

Message Request format:

Type	Value	Description
unsigned long byteCount	[3]	Size of the remainder of this message
unsigned char version	[3]	MP Socket API version
unsigned char opcode	[1]	A number which represents the message type (MPAnnounceClient)
unsigned short port	[1]	Port number which this client's Results Server will be listening to

Message Response format:

Type

Value

Description

unsigned long bytecount

[1]

Size of the remainder of this message

unsigned char status

[0] -> OKAY	Successful transmission
[1] -> RESEND	Try resending
[2] -> BAD_VERSION	API version mismatch
[3] -> BAD_DATA	Invalid data
[4] -> INTERNAL_ERROR	Internal error

Status of the sent message

MPBeginSession message

Message Request format:

Type	Value	Description
unsigned long byteCount	[varies]	Size of the remainder of this message
unsigned char version	[3]	MP Socket API version
unsigned char opcode	[2]	A number which represents the message type (MPBeginSession)
unsigned long srcDomainSize	[varies]	Size of source domain string
unsigned char[] srcDomain	[varies]	Source domain string
unsigned long srcIP	[varies]	Source IP address
unsigned long dstIP	[varies]	Destination IP address
unsigned long usersSize	[varies]	Size of the user data
char[] users	[varies]	Comma-delimited list of users (sender, followed by the recipient(s)). Each user will consist of the user@domain string, optionally followed by a colon-delimited list of attributes for that user

Message Response format:

Type

Value

Description

unsigned long bytecount

[5]

Size of the remainder of this message

unsigned char status

[0] -> OKAY	Successful transmission
[1] -> RESEND	Try resending
[2] -> BAD_VERSION	API version mismatch
[3] -> BAD_DATA	Invalid data
[4] -> INTERNAL_ERROR	Internal error

Status of the sent message

unsigned long sessionID

[varies]

Session ID created for this session

MPSessionData message

Message Request format:

Type	Value	Description
unsigned long bytecount	[varies]	Size of the remainder of this message
unsigned char version	[3]	MP Socket API version
unsigned char opcode	[3]	A number which represents the message type (MPSessionData)
unsigned long sessionID	[varies]	Session ID for this session
unsigned long msgSize	[varies]	Size of the message data
char[] msgData	[varies]	The message data (RFC-822 format)

Message Response format:

Type

Value

Description

unsigned long bytecount

[1]

Size of the remainder of this message

unsigned char status

[0] -> OKAY	Successful transmission
[1] -> RESEND	Try resending
[2] -> BAD_VERSION	API version mismatch
[3] -> BAD_DATA	Invalid data
[4] -> INTERNAL_ERROR	Internal error

Status of the sent message

MPSessionCancel message

Message Request format:

Type	Value	Description
unsigned long bytecount	[6]	Size of the remainder of this message
unsigned char version	[3]	MP Socket API version
unsigned char opcode	[4]	A number which represents the message type (MPSessionCancel)
unsigned long sessionID	[varies]	Session ID for this session

Message Response format:

Type

Value

Description

unsigned long bytecount

[1]

Size of the remainder of this message

unsigned char status

[0] -> OKAY	Successful transmission
[1] -> RESEND	Try resending
[2] -> BAD_VERSION	API version mismatch
[3] -> BAD_DATA	Invalid data
[4] -> INTERNAL_ERROR	Internal error

Status of the sent message

Message Results API

MPSettings message

Message Request format:

Type	Value	Description
unsigned long byteCount	[7]	Size of the remainder of this message
unsigned char version	[3]	MP Socket API version
unsigned char opcode	[1]	A number which represents the message type (MPSettings)
unsigned long maxSize	[varies]	Maximum message size which will be processed (in kbytes)
unsigned char blockTooLarge	[0 or 1]	Block messages which are larger than maxSize.

Message Response format:

Type

Value

Description

unsigned long bytecount

[1]

Size of the remainder of this message

unsigned char status

[0] -> OKAY	Successful transmission
[1] -> RESEND	Try resending
[2] -> BAD_VERSION	API version mismatch
[3] -> BAD_DATA	Invalid data
[4] -> INTERNAL_ERROR	Internal error

Status of the sent message

MPResults message

Message Request format:

Type

Value

Description

unsigned long byteCount

[varies]

Size of the remainder of this message

unsigned char version

[3]

MP Socket API version

unsigned char opcode

[2]

A number which represents the message type (MPResults)

unsigned long sessionID

[varies]

Session ID for this session

unsigned char action

[0] -> PASS
[1] -> BLOCK
[2] -> REPLACE_DATA	For results of MPSessionData message
[3] -> INSPECT_DATA	For results of MPBeginSession message
[4] -> CLONED_DATA	For results of MPSessionData message

This indicates what action the client should take for this email document

unsigned char msgType

[0] -> ENVELOPE	Comma-delimited list of users (sender, followed by the recipient(s)). Each user will consist of the user@domain string.
[1] -> HEADER	SMTP header (RFC-822), minus the extra newline at the end.
[2] -> BODY	SMTP body (RFC-822)

Type of the email document replacement data. This field, along with the following two fields (msgSize and msgData) represent one changed part of an email message. Any combination of the three types of change data may occur, so there may be from zero to three occurrences of change data with each results message. Use the total message size (byteCount) to indicate if there is more change data to process. Only if the action value is REPLACE_DATA

unsigned long msgSize

[varies]

Size of the email document replacement data. Only if the action value is REPLACE_DATA

char[] msgData

[varies]

The email document replacement data. Only if the action value is REPLACE_DATA

unsigned long nclones

[varies]

Number of clones. Only if action is CLONED_DATA

unsigned long cloneEnvDataSz

[varies]

Size of the clone envelope data. Only if action is CLONED_DATA

char[] cloneEnvData

[varies]

Clone envelope data. Only if the action is CLONED_DATA

unsigned long cloneMsgDataSz

[varies]

Size of the clone msg data. Only if action is CLONED_DATA

char[] cloneMsgData

[varies]

Clone message data. Only if the action is CLONED_DATA

Message Response format:

Type

Value

Description

unsigned long bytecount

[1]

Size of the remainder of this message

unsigned char status

[0] -> OKAY	Successful transmission
[1] -> RESEND	Try resending
[2] -> BAD_VERSION	API version mismatch
[3] -> BAD_DATA	Invalid data
[4] -> INTERNAL_ERROR	Internal error

Status of the sent message