#!/usr/pkg/bin/perl -I/usr/pkg/lib
#
# This file is part of DKIMproxy, an SMTP-proxy implementing DKIM.
# Copyright (c) 2010 Jason Long.
# Copyright (c) 2005-2009 Messiah College.
# Written by Jason Long <jlong@messiah.edu>.
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program 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.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA  02110-1301, USA.
#
# This file incorporates work covered by the following copyright and
# permission notice. See the top-level AUTHORS file for more details.
#
#     This code is Copyright (C) 2001 Morgan Stanley Dean Witter, and
#     is distributed according to the terms of the GNU Public License
#     as found at <URL:http://www.fsf.org/copyleft/gpl.html>.
#
#     Written by Bennett Todd <bet@rahul.net>.
#
#
#
#

use warnings;
use strict;

use Getopt::Long;
use Pod::Usage;
use IO::File;
use Sys::Syslog;

use Mail::DKIM 0.20;
use Mail::DKIM::Signer;
use MySmtpServer;
use LookupMap;

#enable support for "pretty" signatures, if available
eval "require Mail::DKIM::TextWrap";

use constant DEFAULT_RELAY_PORT => 25;

my $reject_error = 0;
my @signature_arg;
my $keyfile;
my $selector;
my $domain_arg;
my $identity_arg;
my $dkim_method;
my $domainkeys_method;
my $method;
my $debugtrace = undef;
my $sender_mapfile;
my $listid_mapfile;
my $sender_map;
my $listid_map;

my @default_signatures;

use base "MySmtpProxyServer";
main->run(
		server_type => "PreFork",
	);

sub options
{
	my $self = shift;
	my ($template) = @_;

	$self->SUPER::options(@_);

	# compatibility arguments (older versions of dkimproxy)
	$template->{daemonize} = \$self->{server}->{setsid};
	$template->{pidfile} = \$self->{server}->{pid_file};

	$template->{reject_error} = \$reject_error;
	$template->{sender_map} = \$sender_mapfile;
	$template->{listid_map} = \$listid_mapfile;
	$template->{debugtrace} = \$debugtrace;

	$template->{signature} = \@signature_arg;
	$template->{keyfile} = \$keyfile;
	$template->{selector} = \$selector;
	$template->{dkim_method} = \$dkim_method;
	$template->{domainkeys_method} = \$domainkeys_method;
	$template->{method} = \$method;
	$template->{domain} = \$domain_arg;
	$template->{identity} = \$identity_arg;

	$template->{listen} = \$self->{server}->{listen};
	$template->{relay} = \$self->{server}->{relay};
	$template->{relay_host} = \$self->{server}->{relay_host};
	$template->{relay_port} = \$self->{server}->{relay_port};
}

sub configure
{
	my $self = shift;

	if ($self->isa("Net::Server::MultiType")
		&& !$self->{server}->{server_type})
	{
		# Net::Server::MultiType hasn't done its thing yet,
		# so let it continue. It will call configure() again
		# after it has processed the server_type parameter.
		return $self->SUPER::configure(@_);
	}

	$self->SUPER::configure(@_);

	#
	# At this point, Net::Server should have removed from @ARGV
	# any arguments that it recognized. So any remaining
	# arguments in @ARGV should be for us.
	#
	my $help;
	GetOptions(
			"reject-error" => \$reject_error, #Net::Server doesn't like hyphens
			"help|?" => \$help)
		or pod2usage(2);
	pod2usage(1) if $help;

	if (@ARGV == 2)
	{
		$self->{server}->{listen} = shift @ARGV;
		$self->{server}->{relay} = shift @ARGV;
	}
	pod2usage("Error: wrong number of arguments")
		unless @ARGV == 0;

	if (my $tmp = $self->{server}->{listen})
	{
		my ($host, $port) = split_host_port($tmp);
		$self->{server}->{host} = $host;
		$self->{server}->{port} = [ $port ] if defined $port;
	}
	if (my $tmp = $self->{server}->{relay})
	{
		my ($host, $port) = split_host_port($tmp);
		$self->{server}->{relay_host} = $host;
		$self->{server}->{relay_port} = $port if defined $port
	}

	if (not defined $self->{server}->{port})
	{
		pod2usage("Error: listening port was not specified");
	}
	if (not defined $self->{server}->{relay_host})
	{
		pod2usage("Error: relay host was not specified");
	}

	unless (@signature_arg || defined($sender_mapfile) || defined($listid_mapfile))
	{
		# backwards-compatible... if no --signature argument,
		# and no --sender_map argument, then we create a dkim signature
		@signature_arg = ("dkim");
	}

	foreach my $sig (@signature_arg)
	{
		my $options = parse_signature_options($sig);
		$self->check_signature_options({
			domain => $domain_arg,
			identity => $identity_arg,
			%$options });
		push @default_signatures, $options;
	}

	if ($sender_mapfile)
	{
		$sender_map = LookupMap->load($sender_mapfile);
	}
	if ($listid_mapfile)
	{
		$listid_map = LookupMap->load($listid_mapfile);
	}
}

sub parse_signature_options
{
	my ($options_str) = @_;

	my %option_aliases = (
		key => "keyfile",
		s => "selector",
		d => "domain",
		c => "method",
		a => "algorithm",
		h => "headers",
		i => "identity",
		);

	my $orig_options_str = $options_str;
	unless ($options_str =~ s/^(\w+)//)
	{
		die "invalid signature specifier: '$orig_options_str'\n";
	}
	my $signature_type = $1;

	my $options = {
		keyfile => $keyfile,
		selector => $selector,
		signature => $signature_type,
		};
	if ($signature_type eq "dkim")
	{
		$options->{method} ||= $dkim_method || $method || "relaxed";
	}
	elsif ($signature_type eq "domainkeys")
	{
		$options->{method} ||= $domainkeys_method || $method || "nofws";
	}

	if ($options_str =~ /^\((.*)\)$/)
	{
		my @opts = split /,\s*/, $1;
		foreach my $opt (@opts)
		{
			my ($n, $v) = split /=/, $opt, 2;
			$n = $option_aliases{$n} if exists $option_aliases{$n};
			$options->{$n} = $v;
		}
	}
	elsif ($options_str ne "")
	{
		die "invalid signature specifier: '$orig_options_str'\n";
	}
	return $options;
}

# This is only called at program startup time. It checks signature
# options specified in the config file as part of the "signature"
# option. It does not check signature options specified in a map file,
# e.g. a sender map file or list-id map file.
#
sub check_signature_options
{
	my $self = shift;
	my ($options, $prefix) = @_;

	$prefix ||= "Error";

	unless (defined $options->{keyfile})
	{
		pod2usage("$prefix: no keyfile specified");
	}
	unless (-r $options->{keyfile})
	{
		pod2usage("$prefix: cannot read keyfile $options->{keyfile}");
	}
	unless ($options->{domain})
	{
		pod2usage("$prefix: domain not specified");
	}
	unless (defined $options->{selector})
	{
		pod2usage("$prefix: selector not specified");
	}
	if ($options->{signature} eq "dkim")
	{
		# check method argument
		unless (grep { $options->{method} eq $_ } qw(simple relaxed simple/simple simple/relaxed relaxed/simple relaxed/relaxed nowsp))
		{
			pod2usage("$prefix: invalid method $options->{method}");
		}
	}
	elsif ($options->{signature} eq "domainkeys")
	{
		# check method argument
		unless (grep { $options->{method} eq $_ } qw(simple nofws))
		{
			pod2usage("$prefix: invalid method $options->{method}");
		}
	}
	else
	{
		pod2usage("$prefix: invalid signature type $options->{signature}");
	}
}

sub setup_client_socket
{
	my $self = shift;

	$self->{server}->{relay_port} ||= DEFAULT_RELAY_PORT;

	# create an object for sending the outgoing SMTP commands
	#  (and the signed message)
	my $client = eval { MSDW::SMTP::Client->new(
			interface => $self->{server}->{relay_host},
			port => $self->{server}->{relay_port}) };
	if (my $E = $@)
	{
		chomp $E;
		print "421 Internal error (Next hop is down)\n";
		die "$E\n";
	}
	return $client;
}

sub process_request
{
	my $self = shift;

	# try to determine peer's address
	use Socket;
	my $peersockaddr = getpeername(STDOUT);
	my ($port, $iaddr) = sockaddr_in($peersockaddr);
	$ENV{REMOTE_ADDR} = inet_ntoa($iaddr);

	# initialize syslog
	eval
	{
		openlog("dkimproxy.out", "perror,pid,ndelay", "mail");
		syslog("debug", '%s', "connect from $ENV{REMOTE_ADDR}");
	};
	if (my $E = $@)
	{
		chomp $E;
		print "421 Internal error (Syslog is down)\n";
		die "$E\n";
	}

	$self->{debug} = $debugtrace;

	$self->SUPER::process_request;
}

# handle_end_of_data
#
# Called when the source finishes transmitting the message. This method
# may filter the message and if desired, transmit the message to
# $client. Alternatively, this method can respond to the server with
# some sort of rejection (temporary or permanent).
#
# Usage: $result = handle_end_of_data($server, $client);
#
# Returns:
#   nonzero if a message was transmitted to the next server and its response
#     returned to the source server
#   zero if the message was rejected and the connection to the next server
#     should be dropped
#
sub handle_end_of_data
{
	my $self = shift;
	my $server = $self->{smtp_server};
	my $client = $self->{smtp_client};

	my $fh = $server->{data};
	my $dkim;
	my $result;
	my $result_detail;
	eval
	{
		$dkim = Mail::DKIM::Signer->new(
				Policy => \&signer_policy,
				KeyFile => $keyfile,
				Selector => $selector,
			);

		$dkim->load($fh);

		$result = $dkim->result;
		$result_detail = $dkim->result_detail;

		syslog("info", '%s',
			"DKIM signing - $result_detail; "
			. join(", ", $dkim->message_attributes));
		print STDERR "DKIM signing - $result_detail; "
			. join(", ", $dkim->message_attributes) . "\n";
	};
	if ($@)
	{
		my $E = $@;
		chomp $E;
		$E =~ s/\n/ /gs;
		eval { syslog("warning", '%s', "signing error: $E") };
		print STDERR "Warning: signing error: $E\n";
		$result = "temperror";
		$result_detail = "$result ($E)";
	}

	# check signing result
	if ($result =~ /error$/ && $reject_error)
	{
		# temporary or permanent error
		$server->fail(
			($result eq "permerror" ? "550" : "450")
			. " DKIM - $result_detail");
		return 0;
	}

	$fh->seek(0,0);

	if ($dkim && $dkim->signature)
	{
	#	# output version info
	#	my $DKIM_PROXY_VERSION = "0.15";
	#	$client->write_data_line("X-DKIM-Proxy-Version: "
	#		. "DkimProxy $DKIM_PROXY_VERSION, "
	#		. "Mail::DKIM $Mail::DKIM::VERSION\015\012");

		# output the generated DKIM-Signature
		foreach my $dkim_signature ($dkim->signatures)
		{
			$client->write_data_line($dkim_signature->as_string . "\015\012");
		}

		# followed by the unaltered original message
		$client->yammer($fh);
	}
	else
	{
		# send the message unaltered
		$client->yammer($fh);
	}
	return 1;
}

use Mail::DKIM::Signature;
use Mail::DKIM::DkSignature;

# split the result by commas, but not commas within
# parenthesis
sub split_by_commas
{
	my $left = shift;

	my @result = ();
	# loop until entire is eaten
	while (length $left)
	{
		# find the next item in the comma-separated list
		my $found = "";
		my $depth = 0;
		while ($left =~ s/^(.)//)
		{
			last if $depth <= 0 && $1 eq ",";
			$depth++ if $1 eq "(";
			$depth-- if $1 eq ")";
			$found .= $1;
		}

		# trim whitespace around item
		$found =~ s/^\s+//;
		$found =~ s/\s+$//;
		push @result, $found;
	}
	return @result;
}

sub interpret_macros
{
	my ($options, $signer, $key) = @_;
	my $subst_fn;
	$subst_fn = sub {
			my ($macro) = @_;
			if ($macro eq "key")
			{
				return $key;
			}
			elsif ($macro eq "sender")
			{
				my $sender = $signer->message_sender->address;
				return $sender;
			}
			elsif ($macro =~ /^(.*)domain$/s)
			{
				my $tmp = $subst_fn->($1);
				$tmp = $1 if $tmp =~ /\@([^\@]+)$/;
				return $tmp;
			}
			else
			{
				die "Invalid macro found in signature option: \$$macro\n";
			}
		};

	foreach my $option (qw(domain identity))
	{
		if (defined $options->{$option})
		{
			$options->{$option} =~ s/\$(\w+)/$subst_fn->($1)/es;
			$options->{$option} =~ s/\$\$/\$/;
		}
	}
	return $options;
}

sub get_signature_options
{
	my $signer = shift;

	if ($listid_map)
	{
		# determine what signatures to add based on the
		# "List-Id" header of this message
		if (my $listid = $signer->{headers_by_name}->{"list-id"})
		{
			$listid = $1 if $listid =~ /<(.*?)>/;

			my ($result, $key) = $listid_map->lookup_address($listid);
			if (defined $result)
			{
				if (lc $key eq lc $listid)
				{
					$key = $1 if $key =~ /\.(.*)$/;
				}
				my @result = split_by_commas($result);
				return
					map { interpret_macros($_, $signer, $key) }
					map { +{ domain => $key, %$_ } }
					map { parse_signature_options($_) } @result;
			}
		}
	}

	if ($sender_map)
	{
		# determine what signatures to add based on the domain of the
		# "sender" of this message
		my $sender = $signer->message_sender->address;
		my ($result, $key) = $sender_map->lookup_address($sender);
		if (defined $result)
		{
			$key = $1 if $key =~ /\@(.*)$/;
			my @result = split_by_commas($result);
			return
				map { interpret_macros($_, $signer, $key) }
				map { +{ domain => $key, %$_ } }
				map { parse_signature_options($_) } @result;
		}
	}

	my $domain = $domain_arg;
	if (defined($domain))
	{
		# if multiple domains were specified in the --domain argument,
		# pick one of those domains to use
		my @domains = split /,/, $domain;
		if (@domains > 1)
		{
			# determine which of the available domains to use based
			# on the domain of the "sender" of this message
			my $sender_domain = $signer->message_sender->host;
			$domain = best_domain($sender_domain, @domains)
				or return ();
		}
	}

	return
		map { interpret_macros($_, $signer, $domain) }
		map { +{ domain => $domain, %$_ } }
		@default_signatures;
}

# my $signature_domain = best_domain($message_domain, @key_domains);
#
# $message_domain is the domain of the sender of this message
# @key_domains is a list of domains for which we have signing keys
#
# this function picks one of @key_domains to sign with,
# hopefully matching $message_domain
#
sub best_domain
{
	my ($target_domain, @domains) = @_;

	my $d = $target_domain;
	while (defined $d)
	{
		my ($match) = grep { lc $_ eq lc $d } @domains;
		return $match if $match;

		(undef, $d) = split /\./, $d, 2;
	}
	return undef;
}

sub signer_policy
{
	my ($signer) = @_;

	my @signatures = get_signature_options($signer);
	foreach my $options (@signatures)
	{
		# a DomainKey-Signature should only be added if the
		# signature's domain matches the message's sender
		if ($options->{signature} eq "domainkeys")
		{
			my $message_sender = $signer->message_sender->host;
			my $signature_domain = $options->{domain};
			next unless $message_sender =~ /(^|\.)\Q$signature_domain\E$/is;
		}

		my %signature_type_classes = (
			dkim => "Mail::DKIM::Signature",
			domainkeys => "Mail::DKIM::DkSignature",
			);
		my $cls = $signature_type_classes{$options->{signature}}
			or die "unrecognized signature type: $options->{signature}\n";

		# construct a DKIM-Signature or DomainKey-Signature
		my $sig = $cls->new(
				Algorithm => $options->{algorithm},
				Method => $options->{method},
				Domain => $options->{domain},
				Selector => $options->{selector},
				Identity => $options->{identity},
				Headers => $signer->headers,
				);
		$sig->{KeyFile} = $options->{keyfile};
		$signer->add_signature($sig);
	}
	return; #needed, otherwise Mail::DKIM will add the default signature
}

sub split_host_port
{
	my $str = shift;
	if ($str =~ /^\[(.*)\](?::(\d+))?$/)
	{
		return ($1, $2);
	}
	elsif ($str =~ /^([^:]+):(\d+)$/)
	{
		return ($1, $2);
	}
	return $str;
}

__END__

=head1 NAME

dkimproxy.out - SMTP proxy for adding DKIM signatures to email

=head1 SYNOPSIS

  dkimproxy.out [options] --keyfile=FILENAME --selector=SELECTOR \
                 --domain=DOMAIN LISTENADDR:PORT RELAYADDR:PORT
    smtp options:
      --conf_file=FILENAME
      --listen=LISTENADDR:PORT
      --relay=RELAYADDR:PORT
      --reject-error

    signing options:
      --signature=dkim|domainkeys
      --keyfile=FILENAME
      --selector=SELECTOR
      --method=simple|relaxed|nofws
      --domain=DOMAIN
      --identity=IDENTITY

    daemon options:
      --daemonize
      --user=USER
      --group=GROUP
      --pidfile=PIDFILE

  dkimproxy.out --help
    to see a full description of the various options

=head1 DESCRIPTION

This is the "outbound" part of DKIMproxy, used for adding
DKIM/DomainKey signatures to "outbound" email messages. This program
listens on a particular TCP port (specified by the "listen" option),
and sends the traffic it receives on to a destination TCP address/port
(specified by the "relay" option), with messages getting modified to
have a DKIM and/or DomainKeys signature added.

DKIMproxy offers a number of options that determine how it generates
signatures for the messages it processes. It can also vary its behavior
according to the sender of the message it is processing. Read about
the "sender map file" if you want to vary behavior according to sender.

=head1 OPTIONS

=over

=item B<--daemonize>

If specified, the server will run in the background.

=item B<--domain=DOMAIN>

This argument serves two purposes. First, it selects which messages
(of all those DKIMproxy sees) that should be signed. Second, it
specifies what d= value to put in the generated signatures.

You can specify multiple domains by separating them with commas.
If only one domain is specified, DKIMproxy will sign ALL messages, and
it will use the specified domain as the d= value of all generated
signatures.

If two or more domains are specified, DKIMproxy will only sign messages
which have a sender matching one of these domains. It will use the
matched domain as the d= value of the generated signature.

Please note that the d= value of the generated signature can also be
specified using signature options (see L</"SIGNATURE OPTIONS"). The
signature options will override the value specified here.

Therefore, if you want to sign all messages, and you are specifying
a d= value as part of the "signature" argument, or within a sender map
file or list-id map file, you can omit the "domain" argument.

=item B<--group=GROUP>

If specified, the daemonized process will setgid() to the specified
GROUP.

=item B<--identity=IDENTITY>

If specified, any DKIM signature created will have an i= argument
containing the value specified.

=item B<--keyfile=FILENAME>

This is a required argument. Use it to specify the filename containing
the private key used in signing outgoing messages. For messages to
verify, you will need to publish the corresponding public key in
DNS, using the selector name specified by C<--selector>, under
the domain(s) specified in C<--domain>.

=item B<--listid_map=FILENAME>

If specified, the named file provides signature parameters depending
on the "List-Id" header found in the message. Use this if your mail
server sends out mailing list messages and you want to generate
different signatures depending on which mailing list is sending
messages. See the section below titled L</"LIST-ID MAP FILE">.

=item B<--method=simple|relaxed|nofws>

This option specifies the canonicalization algorithm to use for signing
messages. For DKIM signatures, the options are C<simple>, C<relaxed>,
and C<relaxed/relaxed>; the default is C<relaxed>. For DomainKeys signatures, the
options are C<simple> and C<nofws>; the default is C<nofws>.

=item B<--pidfile=PIDFILE>

Creates a PID file (a file containing the PID of the process) for
the daemonized process. This makes it possible to check the status
of the process, and to cleanly shut it down.

=item B<--reject-error>

This option specifies what to do if an error occurs during signing
of a message. If this option is specified, the message will be rejected
with an SMTP error code. This will result in the MTA sending the message
to try again later, or bounce it back to the sender (depending on the
exact error code used). If this option is not specified, the message
will be allowed to pass through without having a signature added.

The most common cause of an error when signing a message is if the
signature options are improperly configured.

=item B<--selector=SELECTOR>

This is a required argument. Use it to specify the name of the key
selector.

=item B<--sender_map=FILENAME>

If specified, the named file provides signature parameters depending
on what sender is found in the message. See the section below titled
L</"SENDER MAP FILE">.

=item B<--signature=dkim|domainkeys>

This specifies what type of signature to add. Use C<dkim> to sign with
IETF-standardized DKIM signatures. Use C<domainkeys> to sign with
the older, but more common, Yahoo! DomainKeys signatures.
The default is C<dkim>.

This parameter can be specified more than once to add more than one
signature to the message. In addition, per-signature parameters can be
specified by enclosing the comma-separated options in parenthesis after
the signature type, e.g.

  --signature=dkim(c=relaxed,key=/path/to/private.key)

The syntax for specifying per-signature options is described in more
detail in the section below titled L</"SIGNATURE OPTIONS">.

=item B<--user=USER>

If specified, the daemonized process will setuid() to USER after
completing any necessary privileged operations, but before accepting
connections.

=back

=head1 EXAMPLE

For example, if dkimproxy.out is started with:

  dkimproxy.out --keyfile=private.key --selector=postfix \
          --domain=example.org 127.0.0.1:10027 127.0.0.1:10028

the proxy will listen on port 10027 and send the signed messages to
some other SMTP service on port 10028.

=head1 CONFIGURATION FILE

Parameters can be stored in a separate file instead of specifying
them all on the command-line. Use the C<conf_file> option to specify
the path to the configuration file, e.g.

  dkimproxy.out --conf_file=/etc/dkimproxy_out.conf

The format of the configuration file is one option per line:
name of the option, space, then the value of the option. E.g.

  # this is an example config file
  domain example.org,example.com
  keyfile private.key
  selector postfix
  signature dkim

is equivalent to

  dkimproxy.out --domain=example.org,example.com --keyfile=private.key \
                --selector=postfix --signature=dkim

=head1 SIGNATURE OPTIONS

When specifying a signature type, you may optionally specify
per-signature options within parenthesis after the signature type.
E.g. if you say

  dkim(d=example.com,c=relaxed,a=rsa-sha1)

Then DKIMproxy will add a "DKIM" signature with domain C<example.com>,
using the C<relaxed> canonicalization method,
and the C<rsa-sha1> algorithm.

The following signature options are recognized:

=over

=item key

the private key file to use.
You must specify the full path to the private key file.

=item a, algorithm

the algorithm to use

=item c, method

the canonicalization method to use

=item d, domain

the domain to use, default is to use whichever domain was matched
(i.e. one of the domains specified in the --domain argument,
or the domain found in the sender map file.)

You may also use macros for this parameter, such as C<$senderdomain>.
See the section on L</"MACROS"> for more information.

=item i, identity

the identity to use, default is to not include an i= parameter.

You may also use macros for this parameter, such as C<$sender>.
See the section on L</"MACROS"> for more information.

=item s, selector

the selector to use

=back

=head1 MACROS

When specifying signature options, specifically the "domain"
and "identity" options, you may want to substitute values from
the message being signed. The following macros are available:

=over

=item $sender

Substitutes the sender's email address (as found in the Sender or
From header).

=item $senderdomain

Substitutes the domain part of the sender's email address.

=back

=head1 SENDER MAP FILE

If you want to use different signature properties depending on the
sender of the message being signed, use a "sender map file". This
is a lookup file containing sender email addresses on the left
and signature properties on the right. E.g.

  # sign my mail with a EXAMPLE.COM dkim signature
  jason@long.name  dkim(d=example.com)

  # sign WIDGET.EXAMPLE mail with a default domainkeys signature
  widget.example   domainkeys

  # sign EXAMPLE.ORG mail with both a domainkeys and dkim signature
  example.org      dkim(c=relaxed,a=rsa-sha256), domainkeys(c=nofws)

Right-hand values in a sender map file is a comma-separated list of
signature types. Each signature type may have a comma-separated list
of parameters enclosed in parenthesis. See L</"SIGNATURE OPTIONS"> for
more information about the recognized parameters.

Please note that DKIMproxy tries hard to match a given message to an
entry in the sender map file. If the full domain of the message's sender
is not in the file, it tries each parent domain of the message's sender
until a match is found.
E.g. if the sender map file contains the following contents:

  a.my.example     dkim(key=key1)
  my.example       dkim(key=key2)

Then a message from user1@a.my.example will be signed with key key1.
A message from user2@b.my.example will be signed with key2.
A message from user3@your.example will not be signed.

=head1 LIST-ID MAP FILE

This works very much like a sender map file, except it selects based
on the "List-Id" header rather than the "Sender" or "From" header.
You can match on the full list-id value, or just a suffix.
Here is an example file:

  kernel.org                   dkim(d=kernel.org)
  xorg-devel.lists.x.org       dkim(d=lists.x.org)
  dev.spamassassin.apache.org  dkim(d=apache.org)

The syntax of the right-hand values is the same as a sender map file,
i.e. a comma-separated list of signatures to add to the message.
For more details, see L</"SIGNATURE OPTIONS"> above.

If no "List-Id" header is found in the message to be signed, or no
entry in the map file matches the found "List-Id" header,
then DKIMproxy will proceed as if no listid_map option was specified.
That is, it will add the default signature (if a "domain" or
"signature" option was specified), or leave the message as is.

=head1 AUTHOR

Jason Long

=cut
