Skip to Content [alt-c]

batv-tools - a system for stopping backscatter

batv-tools implements Bounce Address Tag Validation, a system for filtering backscatter. Briefly, BATV works as follows:

  1. The envelope sender of all outgoing mail is rewritten ("signed") to contain a cryptographic token. If the message bounces, it is bounced to this address.
  2. The envelope recipient of all incoming bounces is checked for a valid token. If a bounce has a missing or invalid token, it's obviously not in reply to a real message and can be filtered.

BATV is described by an Internet Draft which was last revised in 2008. batv-tools implements the draft standard, but also supports an alternative address meta-syntax based on sub-addressing, described below.

batv-tools provides both a milter (batv-milter) and a collection of standalone tools (batv-sign, batv-validate, batv-sendmail) that do signing and validation. The standalone tools enable individual users to use BATV without the involvement of their system administrators.

How batv-tools Works

Outgoing mail is passed through either batv-milter or batv-sign. If a BATV key exists for the envelope sender, the envelope sender is rewritten to be a signed BATV address.

Incoming mail is passed through either batv-milter or batv-validate. The envelope recipient is validated and the result of the validation is placed in the X-Batv-Status header. If the envelope recipient contains a valid BATV signature, it is rewritten to its original non-BATV form.

batv-milter can be configured to reject bounces which aren't addressed to a valid BATV signature, but by default, it is the user's responsibility to filter mail based on the X-Batv-Status header.

Getting batv-tools

Building from Source (latest official release)

Download and extract batv-tools-0.8.tar.gz (PGP signature) and run:

cd batv-tools-0.8

make

make install

To install to a specific location:

make install PREFIX=/usr/local

To build only the standalone tools (and not the milter):

make all-tools

make install-tools

Building from Git (development version; less stable and with no compatibility guarantee)

git clone https://www.agwa.name/git/batv-tools.git

cd batv-tools

make

make install

Verifying the Source

Since version 0.6, all tarballs and Git tags are signed by my PGP key, EF5D 84C1 838F 2EB6 D896 8C04 1037 8EFC 2080 080C.

Getting Up and Running

See doc/quickstart.milter.txt and doc/quickstart.standalone.txt in the source for instructions on getting up-and-running quickly.

Dependencies

The standalone tools have no external dependencies.

To use the milter, you need:

  • libmilter, from Sendmail 8.14.0 or higher
  • Postfix 2.6 or higher, Sendmail 8.14.0 or higher, or a MTA with equivalent milter functionality

Build Dependencies

To build batv-tools, you need:

  • make
  • A C++ compiler (e.g. gcc)

To build the milter, you also need:

  • Development headers for libmilter, from Sendmail 8.14.0 or higher

Current Status

The current version of batv-tools is 0.8, released on 2016-03-13. batv-tools aims to be bug-free and reliable, meaning it shouldn't crash, malfunction, or do horrible things to your mail. However, it has not reached maturity, meaning it is not as documented, featureful, or easy-to-use as it should be.

As of 2019, batv-tools is no longer under active development. Serious bugs will be fixed, but new features are unlikely to be added

Sub-Address Meta-Syntax

batv-tools supports an alternative address meta-syntax based on sub-addressing (aka "plus" addressing). Instead of rewriting the entire local part of the email address, the BATV token is appended to the local part after a sub-address delimiter (typically '+' or '-'). For example:

andrew+prvs=9352e50792@example.com

Since many mail systems support sub-addressing, this syntax permits BATV-signed mail to be routed through mail servers that have no knowledge of BATV. This has a couple advantages:

  1. Backup MX servers which accept mail only for known recipients need not support BATV. As long as they support sub-addressing, mail destined to BATV addresses will be accepted. (In contrast, the standard meta-syntax appears to the backup MX server as an unknown recipient, meaning the backup MX server must either accept all mail regardless of recipient (a bad idea), or support BATV (not always feasible).)
  2. It lets individual users use BATV with support from their MUA and/or MDA, without the MTA needing to support BATV. The standalone BATV tools support only the non-standard sub-address syntax (otherwise MTA support would be required). The milter uses the standard syntax by default but may be configured to use sub-address syntax.

Project Resources

For help or questions, send mail to the discussion list, batv-tools-discuss@lists.cloudmutt.com. To report a bug or make a feature request, please open an issue at GitHub or send mail to the discussion list. To contribute code, please send a properly-formatted patch to the discussion list, or open a pull request at GitHub.

To learn about new releases, subscribe to the announcement list, or watch the GitHub project.

Documentation and Examples

Legalese

Copyright © 2013 Andrew Ayer

Licensed predominantly under the GPLv3 with OpenSSL Linking Exception. Also contains code licensed under more permissive GPL-compatible licenses.

batv-tools is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.