NAME
Mail::DMARC - Perl implementation of DMARC
VERSION
version 0.20130514
SYNOPSIS
DMARC: Domain-based Message Authentication, Reporting and Conformance
A reliable means to authenticate who mail is from, at internet scale.
DESCRIPTION
Determine if:
a. the header_from domain exists
b. the header_from domain publishes a DMARC policy
c. does the message conform to the published policy?Results of DMARC processing are stored in a Mail::DMARC::Result object.
CLASSES
Mail::DMARC - A perl implementation of the DMARC draft
Mail::DMARC::DNS - DNS functions used in DMARC
Mail::DMARC::Policy - a DMARC record in object format
Mail::DMARC::PurePerl - a DMARC implementation
Mail::DMARC::Report - the R in DMARC
Mail::DMARC::Report::Send - deliver formatted reports via SMTP & HTTP
Mail::DMARC::Report::Receive - parse incoming email and HTTP reports to store
Mail::DMARC::Report::Store - a persistent data store for DMARC reports
Mail::DMARC::Report::View - CLI and (eventually) CGI methods for report viewing
Mail::DMARC::libopendmarc - an XS implementation using libopendmarc
HOW TO USE
my $dmarc = Mail::DMARC->new( "see L<new|#new> for required args");
my $result = $dmarc->verify();
if ( $result->evaluated->result eq 'pass' ) {
...continue normal processing...
return;
};
# any result that did not pass is a fail. Now for disposition
if ( $result->evalated->disposition eq 'reject' ) {
...treat the sender to a 550 ...
};
if ( $result->evalated->disposition eq 'quarantine' ) {
...assign a bunch of spam points...
};
if ( $result->evalated->disposition eq 'none' ) {
...continue normal processing...
};There's a lot more information available in the $result object. See Mail::DMARC::Result page for complete details.
METHODS
new
Create an empty DMARC object. Then populate it and run the request:
my $dmarc = Mail::DMARC->new;
$dmarc->source_ip('192.0.1.1');
$dmarc->envelope_to('recipient.example.com');
$dmarc->envelope_from('sender.example.com');
$dmarc->header_from('sender.example.com');
$dmarc->dkim( $dkim_verifier );
$dmarc->spf(
domain => 'example.com',
scope => 'mfrom',
result => 'pass',
);
my $result = $dmarc->verify();Alternatively, you can pass in all the required parameters in one shot:
my $dmarc = Mail::DMARC->new(
source_ip => '192.0.1.1',
envelope_to => 'example.com',
envelope_from => 'cars4you.info',
header_from => 'yahoo.com',
dkim => $dkim_results, # same format
spf => $spf_results, # as previous example
);
my $result = $dmarc->verify();source_ip
The remote IP that attempted sending the message. DMARC only uses this data for reporting to domains that request DMARC reports.
envelope_to
The domain portion of the RFC5321.RcptTo, (aka, the envelope recipient), and the bold portion in the following example:
RCPT TO:<user@example.com>
envelope_from
The domain portion of the RFC5321.MailFrom, (aka, the envelope sender). That is the the bold portion in the following example:
MAIL FROM:<user@example.com>
header_from
The domain portion of the RFC5322.From, aka, the From message header.
From: Ultimate Vacation <sweepstakes@example.com>
You can instead pass in the entire From: header with header_from_raw.
header_from_raw
This retrieves the header_from domain by extracing it from a raw From field/header. The domain portion is extracted by Mail::DMARC::PurePerl::get_dom_from_header, which is fast, generally effective, but also rather crude. It does have limits, so read the description.
dkim
The dkim method accepts an array reference. Each array element represents a DKIM signature in the message and consists of the 4 keys shown in this example:
$dmarc->dkim( [
{
domain => 'example.com',
selector => 'apr2013',
result => 'fail',
human_result=> 'fail (body has been altered)',
},
{
# 2nd signature, if present
},
] );If you used Mail::DKIM::Verifier to validate the message, just pass in the Mail::DKIM::Verifier object that processed the message:
$dmarc->dkim( $dkim_verifier );domain
The d= parameter in the signature
selector
The s= parameter in the signature
result
The validation results of this signature. One of: none, pass, fail, policy, neutral, temperror, or permerror
human result
Additional information about the DKIM result. This is comparable to Mail::DKIM::Verifier->result_detail.
spf
The spf method accepts a hashref or named arguments:
$dmarc->spf(
domain => 'example.com',
scope => 'mfrom',
result => 'pass',
);The SPF domain and result are required for DMARC validation and the scope is used for reporting.
domain
The SPF checked domain
scope
The scope of the checked domain: mfrom, helo
result
The SPF result code: none, neutral, pass, fail, softfail, temperror, or permerror.
AUTHORS
Matt Simerson <msimerson@cpan.org>
Davide Migliavacca <shari@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by The Network People, Inc..
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.