News


FAQ


Documentation


Mailing List


Downloads


Links
 GOSSiP Guide for Milter Writers

 If you're interested in writing a milter, there are four things you need to know:
  1. How to formulate a GOSSiP query
  2. How to connect to a GOSSiP node
  3. What to expect in response to a query
  4. How to react to the response


How to formulate a GOSSiP query

A GOSSiP query consists of five colon-delimited components followed by a blank line:
  1. A query indicator tag "Q"
  2. The right-hand-side (RHS) of the RFC2821 MAIL FROM: input from the sender
  3. The IP with which the sender has connected to the MTA
  4. A Time To Live(TTL) value for the query
  5. An Unique Message Identification String (UMIS)
<tag>:<rhs>:<ip>:<ttl>:<umis>
<CR>

A typical query would look like this:
Q:example.org:192.168.1.5:5:fa5a055a6e797e6fa54fd61996dacebfab3a434
<CR>


  • The RHS should be parsed from the RFC2821 MAIL FROM: input received from the MTA.
  • The IP should be supplied by the MTA.
  • The TTL should be read from a configuration file or command line.  It should apply to all queries sent from the milter.
  • The UMIS should be unique.  The one in the example above was generated by using a double-SHA1 hash on the query string plus a strong nonce.  You can use whatever method you desire, but the UMIS must be consistent for every milter that sends queries to a particular GOSSiP node, and they must be unique (within reason).  UMIS values are cached for a limited time, so overlap should be minimized overall, and eliminated during the cache length (which is determined at the time of GOSSiP node deployment).

How to Connect to a GOSSiP Node

The milter will generally be connecting to a GOSSiP node controlled by the same individual or group that controls the MTA calling your milter.  However, this may not always be the case.  Therefore, the GOSSiP node will allow both unencrypted and SSL-encrypted connections.

The hostname or IP address and port that the milter uses to connect to the GOSSiP node should be read in from a configuration file, the command line, or otherwise supplied to the milter. 

Connections to the GOSSiP node are threaded; multiple simultaneous connections to the node are possible.

For SSL connections, the node will accept SSLv2, SSLv3, and TLSv1 protocols.  However, I strongly urge you not to use SSLv2, as it is known to have been compromised.  The GOSSiP node will not request a certificate from the milter.  However, I encourage you to verify the certificate supplied by the GOSSiP node.  The GOSSiP node is capable of SSL session caching.

For non-SSL connections, standard Berkeley socket protocol is sufficient.  The GOSSiP node should be configured to accept connections in the manner you've told the milter to connect, and on the port the milter's attempting to connect to.

For all connections, the milter should time out and respond with the appropriate no-op to the MTA before the MTA times out waiting for a response from the milter.  At least one MTA will send a 450 to the sender if the milter is behaving badly.



What to Expect in Response to a Query

Once the GOSSiP node has finished the query propagation process and has formulated a final score for the identity, it will respond with a string containing an MTA directive and four colon-delimited components, followed by a blank line:
  1. an mta directive
  2. a header to be inserted into the incoming message
  3. the UMIS for the query
  4. the identity's reputation score
  5. the confidence value for that score
<directive><SPACE><header>:<umis>:<reputation score>:<confidence value>
<CR>

A typical response would look like this:
PREPEND X-GOSSiP: fa5a055a6e797e6fa54fd61996dacebfab3a434:67:23
<CR>


The reputation score will be an integer between -100 and +100. 
The confidence value will be an integer between 0 and +100.
The UMIS will match that supplied by the milter in the original query.


How to React to the Query Response

Once the milter has received the response from the GOSSiP node, you have to decide what to do about it.  One option is to simply insert the "X-GOSSiP:" header into every message along with the response from the GOSSiP node, and tell the MTA to accept the incoming mail.  The other possibility is to allow the person deploying the milter to specify response criteria under which the milter will tell  the MTA to reject the incoming mail, and otherwise insert the "X-GOSSiP:" header and accept the message.

The milter should then clean up after itself and exit (if required by the MTA).