BDKIM

BDKIM ("Bridge to DKIM" or "Boxbe DKIM") is two pieces of software. Together they form a networked bridge from Java to the Mail::DKIM Perl module, allowing you to easily verify the DomainKeys and DKIM signatures for a given message. You could also write your own client (in whatever language) to talk to the BDKIM perl server. This distribution also includes an example usage Java class.

On the Perl side, BDKIM runs as a simple server listening on a port, speaking a custom protocol. This distribution includes a Java client for that server. You can use the handy methods in the Java client to do your DK/DKIM evaluation, or write your own client to communicate with the BDKIM daemon. BDKIM does not support signing of messages, only verification.

There are Java-based DK/DKIM solutions, as well as mail server plugins, but none are as thorough and featured as Mail::DKIM for obtaining the finer details (e.g. individual results for each signature present, information on which headers were signed by the signature, etc).

This software was developed for and is used by Boxbe to do much of its DK/DKIM evaluation. The core is stable, thoroughly tested (literally billions of emails have been evaluated), and now open-source. To prepare this distribution, however, some changes and improvements were made to the code, so it can't strictly be said to be thoroughly tested as-is. It was designed on and runs on Linux. It may not work on Windows, or other systems, without modification (e.g. I don't think Net::Server::PreFork works on Windows; not sure about other platforms). Let me know if you get it going on anything besides Linux. BDKIM should at least be compatible with Mail::DKIM versions 0.33 through the current version as of this writing, 0.39. Let me know if you use it with an earlier version.

To use BDKIM, first copy the main BDKIM and BDKIM.conf files to whatever directory you choose (they must be in the same directory, and it will generate a log file and a .pid file when run), edit BDKIM.conf to suit your needs, and start the BDKIM daemon. In the scripts/ directory of this distribution you will find a few helpful bash shell scripts to aid in the process of starting and stopping the daemon. They aren't very fancy, and just exist to automatically check for a BDKIM.pid file to prevent accidentally starting up a duplicate server. You can invoke BDKIM directly or use the scripts (see the scripts for simple syntax on starting BDKIM directly.) startBDKIM, for example, could be used like this:

$ ./startBDKIM /path/to/bdkim/directory/

Starting BDKIM directly (without attention to any servers already running) is simple:

$ ./BDKIM

A sample init.d script is also included.

On the Java side, you simply instantiate a BdkimAnalyzer, configure it properly (hostname, port, etc) and pass it the email message text. It will send your email message to the perl process, interpret the results that come back, and return to you the detailed (per-signature) DK or DKIM results in a SignatureResults object.

Notes:

• The default character set encodings need to be the same for your Perl and Java environments. The odds are good that they already are, but if you have trouble, check that out.
• BDKIM is configured by default to a max message size of 20MB (it will abort processing of larger messages). See BDKIM.conf for more info.
• This package uses a unified version number for the Perl and Java code and all associated scripts.

See the code (both BDKIM and BdkimAnalyzer.java) for more information on usage and configuration, as well as other handy methods.

The Perl side is based on Net::Server::PreFork -- your Java process connects via TCP/IP and the parent daemon hands off your request to a child process to do the evaluation (it easily handles multiple simultaneous requests).

Mail::DKIM is reasonably efficient: it avoids unnecessary buffer copies and so forth, but there are a few places it could be improved. If you are processing a huge volume of messages, you may need to consider performance issues if you are evaluating the DK/DKIM status of every message (remember that the entirety of the message will be sent over loopback (or the net) to BDKIM before processing begins. The Java client is smart enough to avoid sending messages without DK/DKIM headers, and the BDKIM side is smart enough to efficiently handle messages with malformed headers, but most often evaluating DK/DKIM means canonicalizing and doing math on the entirety of the message contents.)

If you have any questions or issues, feel free to get in touch.