edu.harvard.deas.hyperenc
Class EmailHyperCommunicator

java.lang.Object
  edu.harvard.deas.hyperenc.EmailHyperCommunicator

All Implemented Interfaces:

HyperCommunicator

public class EmailHyperCommunicator
extends Object
implements HyperCommunicator

Sends and receives messages via e-mail. Each EmailHyperCommunicator sends and receives messages for a particular e-mail account. Clients may request that messages be sent from that account, and may check for incoming messages to that account.

The presence of an e-mail header with the name specified in HYPERENC_HEADER indicates that the e-mail contains a hyper-encrypted message. E-mail messages without this header are ignored. The value of the header indicates the format of the body. The only format currently supported is "text"; that format is described below. Future implementations may support XML-based bodies or other formats.

The address specified in the From: e-mail header corresponds to the sender field of a HyperMessage. The address specified in the To: header corresponds to the recipient field of a HyperMessage. If the e-mail Message has more than one recipient, all but the first are ignored. These addresses are converted to their corresponding Contacts by looking up the Address in the ContactList provided at construction.

Message format

The "text" format is a hastily-assembled, somewhat fragile format for encoding hyper-encryption messages. Future versions will support improved formats (XML-based, for example).

An e-mail body with the "text" format has five sections, which may appear in any order: type, block list, MAC, subject, and content. (Message produced by this class give the five sections in that order.) The sections may be separated by any number of newlines; leading and trailing whitespace in all sections is ignored.

• The type section starts with the header string "*TYPE*" on its own line. The next line contains a token indicating the type of the message. That token must be a string representation of a HyperMessageType. This corresponds to the type field of a HyperMessage.
• The block list section starts with the header string "*PADSUSED*" on its own line. The next one or more lines contain zero or more integers, each separated by any amount of whitespace (including newlines), identifying the IDs of blocks that were used to encrypt the message. These integers, in order, correspond to the padsUsed field of a HyperMessage.
• The MAC section starts with the header string "*MAC*" on its own line. The next line contains a 256-bit HEMAC-SHA256, encoded as a 64-character hex string. The next line contains eight encryption block IDs, separated by spaces; these are the eight blocks used in computation of the HEMAC-SHA1, as described in HyperMAC. If the message does not contain a MAC, the MAC section must still be present, but contains only whitespace.
• The subject section starts with the header string "*SUBJECT*" on its own line. When parsing this section, leading and trailing whitespace is stripped, and newlines are replaced by spaces. This corresponds to the subject field of a HyperMessage.
• The content section starts with the header string "*CONTENT*" on its own line. When parsing this section, leading and trailing whitespace (other than newlines) is stripped; newlines are preserved. This corresponds to the content field of a HyperMessage.

See Also:

ContactList, HyperMAC

Field Summary

static String

HYPERENC_HEADER

Constructor Summary

EmailHyperCommunicator(Properties accountInfo, ContactList contactList)
Creates a new EmailHyperCommunicator with the given account information.

Method Summary

protected Message	makeMessage(HyperMessage hm, Session session) Converts an HyperMessage into a Message containing the same data.
protected HyperMessage	processMessage(Message msg) Create a HyperMessage from the given Message.
List<HyperMessage>	receive() Retrieves incoming messages from the e-mail server.
void	send(HyperMessage hm) Send a HyperMessage via e-mail.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HYPERENC_HEADER

public static final String HYPERENC_HEADER

See Also:

Constant Field Values

Constructor Detail

EmailHyperCommunicator

public EmailHyperCommunicator(Properties accountInfo,
                              ContactList contactList)

Creates a new EmailHyperCommunicator with the given account information. All e-mails sent from or received by this EmailHyperCommunicator use the account defined by this information.

Parameters:

accountInfo - a Properties object holding the account details for the e-mail account this EmailHyperCommunicator should use.

contactList - a list of Contacts; the EmailHyperCommunicator uses this list to look up the Contact that corresponds to a given Address

Method Detail

send

public void send(HyperMessage hm)

Send a HyperMessage via e-mail. Converts hm to a Message using makeMessage, then sends it over a Transport created using this EmailHyperCommunicator's account info.

Specified by:

send in interface HyperCommunicator

Parameters:

hm - the HyperMessage to be sent

makeMessage

protected Message makeMessage(HyperMessage hm,
                              Session session)

Converts an HyperMessage into a Message containing the same data. The returned Message is constructed using the account information from this Transmitter and is ready to be sent via e-mail.

The format of the returned Message is specified by the documentation for the EmailHyperCommunicator class.

Parameters:

hm - HyperMessage to be converted

session - the Session containing mail properties used to send this message

Returns:

Message containing the data from hm

receive

public List<HyperMessage> receive()

Retrieves incoming messages from the e-mail server. Converts incoming Messages to HyperMessages using processMessage.

Specified by:

receive in interface HyperCommunicator

Returns:

a list of HyperMessages that have been received since the last time this method was called

processMessage

protected HyperMessage processMessage(Message msg)
                               throws MessageParseException

Create a HyperMessage from the given Message. If the given Message is not a hyper-encryption protocol message or a hyper-encrypted message, returns null. If msg does not have a received date (obtained via getReceivedDate()), the current time is used.

The recipient and sender Address of the message are converted to Contacts using the contactMap with which this HyperCommunicator was constructed.

The format expected when parsing the given Message is specified by the documentation for the EmailHyperCommunicator class.

Parameters:

msg - The received Message

Returns:

a HyperMessage built using the data parsed from msg, or null if msg is not a hyper-encryption message

Throws:

MessageParseException - if the body of msg could not be parsed