|GOSSiP Guide for Milter Writers
If you're interested in writing a milter, there are four things you need to know:
How to formulate a GOSSiP query
A GOSSiP query consists of five colon-delimited components followed by a blank line:
A typical query would look like this:
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:
<directive><SPACE><header>:<umis>:<reputation score>:<confidence value>
A typical response would look like this:
PREPEND X-GOSSiP: fa5a055a6e797e6fa54fd61996dacebfab3a434:67:23
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).