EMAIL PARSER module descritpion

EP is a module that provides facilities to explode
a mail message into its basic units.
In general, a mail message can be composed with MIME
headers and can include authentication information
with PGP logics.

Basically, a mail message is parsed via <EP_ParseMail>.
This function builds a tree representing all the unsplitable
components of a mail message.
The parsing is accomplished using two distinct tools,
a MIME parser and a PGP parser.
The algorithm to unfold a mail message first process a 
buffer to decompose it looking at MIME headers.
Then, when MIME parser can't go further in exploding the buffer,
it passes the buffer to the PGP parser.
This looks for PGP headers and try to, if necessary, decrypt 
and verify a signature, if present. 
In case PGP headers are found, the inner part of
the PGP parsed message are re-sent to the MIME parser.
The whole procedure stops in case a buffer can't be
reducted by MIME and PGP parser, then it becames a leaf of the 
resulting tree.

The leaves are the minimal reduction possible with the supported
MIME and PGP headers recognition algorithms.

It's worth mentioning that MIME parser has been devised with
the possibility to add new drivers for other MIME headers.
It should automatically lookup for the correct driver to 
process a defined header.

A short list of supported MIME headers:

- Multipart signed
- Multipart alternative
- Multipart mixed
- Multipart unknown
- PGP plain
- Application PGP
- Text Plain

EP PARSING TREE STRUCTURE

EP_ParseMail produces a structure of this type:

typedef struct Mail_Descr {
  Mail_Header_Field *from;
  Mail_Header_Field *subject;
  Mail_Header_Field *date;
  Mail_Header_Field *message_id;
  Mail_Header_Field *reply_to;
  Mail_Header_Field *cc;
  Mail_Header_Field *content_type;
  EPNodePtr tree;
} EP_Mail_Descr;

The <tree> field contains the parsing tree. Each node
has the following structure:

typedef struct EPNode {
  int       nodeID;
  short     isValidPGPSignature;
  t_MM_type MIMEContentType;
  u32       keyID;
  char      *file;
  EPNodePtr inner;
  EPNodePtr next;
} EP_mail_node;

<nodeID>: a serial number that represents a single node
          key for a given message.
	  The buffer file of a node has the following
	  name nomenclature: 
	  "EPtmp.<hostname>.<PID>.<nodeID>"
	  Files are created on a path provided to 
	  the EP_ParseMail funtion;

<isValidPGPSignature>:
	a flag describing the PGP properties of a buffer.
	Possible values are:
  vS_IS_VALID,             => Signature has been positively verified
  vS_IS_NOT_PGP,	   => The message hasn't any PGP headers
  vS_KO,		   => Signature is not valid
  vS_CRC_ERROR,		   \
  vS_NO_PUBLIC_KEY,	    |
  vS_NO_OPENPGP_DATA,	    |
  vS_NO_IN_FILES,	     => Several error conditions 
  vS_NO_OUT_FILES,	    |
  vS_TO_BE_PGPVERIFIED,	    |
  vS_UNABLE_TO_WRITE_FILE  /

<MIMEContentType> : 
       describes the MIME type of the related buffer.
       Values:
       	    -1 => not MIME
	    ....

<keyID>: the signature's key ID;

<file>:  filename of the produced buffer;

<inner>: pointer to the first exploded node of the buffer
	 described by the current node;
<next>:  pointer to the following node that describe the next 
	 part of the parent message.



The user of EP module has a postprocessor function to
build the resulting data structure. A function called
<EP_GetTokens> is feeded with the root node of the
parsing tree and it builds a list containing the leaves
of the tree.
For each node on the list, another list <EPTokenKeys>
is built in order to gather all the key informations for
the related node. 
Thus, the user needs only to scan this list and, for 
each token, reads the result of the PGP key verifications
on the fields <isValidPGPSignature> and <keyID> of the
EPTokenKeys list.


FP