.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::DKIM::Verifier 3"
.TH Mail::DKIM::Verifier 3 "2013-02-07" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::DKIM::Verifier \- verifies a DKIM\-signed message
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mail::DKIM::Verifier;
\&
\&  # create a verifier object
\&  my $dkim = Mail::DKIM::Verifier\->new();
\&
\&  # read an email from a file handle
\&  $dkim\->load(*STDIN);
\&
\&  # or read an email and pass it into the verifier, incrementally
\&  while (<STDIN>)
\&  {
\&      # remove local line terminators
\&      chomp;
\&      s/\e015$//;
\&
\&      # use SMTP line terminators
\&      $dkim\->PRINT("$_\e015\e012");
\&  }
\&  $dkim\->CLOSE;
\&
\&  # what is the result of the verify?
\&  my $result = $dkim\->result;
\&
\&  # there might be multiple signatures, what is the result per signature?
\&  foreach my $signature ($dkim\->signatures)
\&  {
\&      print "signature identity: " . $signature\->identity . "\en";
\&      print "verify result: " . $signature\->result_detail . "\en";
\&  }
\&
\&  # the alleged author of the email may specify how to handle email
\&  foreach my $policy ($dkim\->policies)
\&  {
\&      die "fraudulent message" if ($policy\->apply($dkim) eq "reject");
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The verifier object allows an email message to be scanned for \s-1DKIM\s0 and
DomainKeys signatures and those signatures to be verified. The verifier
tracks the state of the message as it is read into memory. When the
message has been completely read, the signatures are verified and the
results of the verification can be accessed.
.PP
To use the verifier, first create the verifier object. Then start
\&\*(L"feeding\*(R" it the email message to be verified. When all the _headers_
have been read, the verifier:
.PP
.Vb 4
\& 1. checks whether any DomainKeys/DKIM signatures were found
\& 2. queries for the public keys needed to verify the signatures
\& 3. sets up the appropriate algorithms and canonicalization objects
\& 4. canonicalizes the headers and computes the header hash
.Ve
.PP
Then, when the _body_ of the message has been completely fed into the
verifier, the body hash is computed and the signatures are verified.
.PP
The results of the verification can be checked with \*(L"\fIresult()\fR\*(R"
or \*(L"\fIsignatures()\fR\*(R".
.PP
Messages that do not verify may be checked against the alleged sender's
published signing policy with \*(L"\fIpolicies()\fR\*(R" and
\&\*(L"\fIapply()\fR\*(R" in Mail::DKIM::Policy.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "\fInew()\fP"
.IX Subsection "new()"
Constructs an object-oriented verifier.
.PP
.Vb 1
\&  my $dkim = Mail::DKIM::Verifier\->new();
\&
\&  my $dkim = Mail::DKIM::Verifier\->new(%options);
.Ve
.PP
The only option supported at this time is:
.IP "Debug_Canonicalization" 4
.IX Item "Debug_Canonicalization"
if specified, the canonicalized message for the first signature
is written to the referenced string or file handle.
.SH "METHODS"
.IX Header "METHODS"
.SS "\s-1\fIPRINT\s0()\fP"
.IX Subsection "PRINT()"
Feeds part of the message to the verifier.
.PP
.Vb 3
\&  $dkim\->PRINT("a line of the message\e015\e012");
\&  $dkim\->PRINT("more of");
\&  $dkim\->PRINT(" the message\e015\e012bye\e015\e012");
.Ve
.PP
Feeds content of the message being verified into the verifier.
The \s-1API\s0 is designed this way so that the entire message does \s-1NOT\s0 need
to be read into memory at once.
.PP
Please note that although the \s-1\fIPRINT\s0()\fR method expects you to use
SMTP-style line termination characters, you should \s-1NOT\s0 use the
SMTP-style dot-stuffing technique described in \s-1RFC 2821\s0 section 4.5.2.
Nor should you use a <\s-1CR\s0><\s-1LF\s0>.<\s-1CR\s0><\s-1LF\s0> sequence to terminate the
message.
.SS "\s-1\fICLOSE\s0()\fP"
.IX Subsection "CLOSE()"
Call this when finished feeding in the message.
.PP
.Vb 1
\&  $dkim\->CLOSE;
.Ve
.PP
This method finishes the canonicalization process, computes a hash,
and verifies the signature.
.SS "\fIfetch_author_domain_policies()\fP"
.IX Subsection "fetch_author_domain_policies()"
Retrieves \s-1ADSP\s0 records from \s-1DNS.\s0
.PP
.Vb 5
\&  my @policies = $dkim\->fetch_author_domain_policies;
\&  foreach my $policy (@policies)
\&  {
\&      my $policy_result = $policy\->apply($dkim);
\&  }
.Ve
.PP
This method will retrieve all applicable
\&\*(L"author-domain-signing-practices\*(R" published in \s-1DNS\s0 for this message.
Author policies are keyed to the email address(es) in the From: header,
i.e. the claimed author of the message.
.PP
This method returns a *list* of policy records, since there is allowed
to be zero or multiple email addresses in the From: header.
.PP
The result of the \fIapply()\fR method is one of: \*(L"accept\*(R", \*(L"reject\*(R", \*(L"neutral\*(R".
.PP
See also: \*(L"\fIpolicies()\fR\*(R".
.SS "\fIfetch_author_policy()\fP"
.IX Subsection "fetch_author_policy()"
Retrieves a signing policy from \s-1DNS.\s0
.PP
.Vb 2
\&  my $policy = $dkim\->fetch_author_policy;
\&  my $policy_result = $policy\->apply($dkim);
.Ve
.PP
This method retrieves the \s-1DKIM\s0 Sender Signing Practices
record as described in Internet Draft draft\-ietf\-dkim\-ssp\-00\-01dc.
This Internet Draft is now obsolete; this method is only kept for
backward-compatibility purposes.
.PP
Please use the \*(L"\fIpolicies()\fR\*(R" method instead.
.SS "\fIfetch_sender_policy()\fP"
.IX Subsection "fetch_sender_policy()"
Retrieves a signing policy from \s-1DNS.\s0
.PP
.Vb 2
\&  my $policy = $dkim\->fetch_sender_policy;
\&  my $policy_result = $policy\->apply($dkim);
.Ve
.PP
The \*(L"sender\*(R" policy is the sender signing policy as described by the
DomainKeys specification, now available in \s-1RFC4870\s0(historical).
I call it the \*(L"sender\*(R" policy because it is keyed to the email address
in the Sender: header, or the From: header if there is no Sender header.
This is the person whom the message claims as the \*(L"transmitter\*(R" of the
message (not necessarily the author).
.PP
If the email being verified has no From or Sender header from which to
get an email address (which violates email standards),
then this method will \f(CW\*(C`die\*(C'\fR.
.PP
The result of the \fIapply()\fR method is one of: \*(L"accept\*(R", \*(L"reject\*(R", \*(L"neutral\*(R".
.PP
See also: \*(L"\fIpolicies()\fR\*(R".
.SS "\fIload()\fP"
.IX Subsection "load()"
Load the entire message from a file handle.
.PP
.Vb 1
\&  $dkim\->load($file_handle);
.Ve
.PP
Reads a complete message from the designated file handle,
feeding it into the verifier. The message must use <\s-1CRLF\s0> line
terminators (same as the \s-1SMTP\s0 protocol).
.SS "\fImessage_originator()\fP"
.IX Subsection "message_originator()"
Access the \*(L"From\*(R" header.
.PP
.Vb 1
\&  my $address = $dkim\->message_originator;
.Ve
.PP
Returns the \*(L"originator address\*(R" found in the message, as a
Mail::Address object.
This is typically the (first) name and email address found in the
From: header. If there is no From: header,
then an empty Mail::Address object is returned.
.PP
To get just the email address part, do:
.PP
.Vb 1
\&  my $email = $dkim\->message_originator\->address;
.Ve
.PP
See also \*(L"\fImessage_sender()\fR\*(R".
.SS "\fImessage_sender()\fP"
.IX Subsection "message_sender()"
Access the \*(L"From\*(R" or \*(L"Sender\*(R" header.
.PP
.Vb 1
\&  my $address = $dkim\->message_sender;
.Ve
.PP
Returns the \*(L"sender\*(R" found in the message, as a Mail::Address object.
This is typically the (first) name and email address found in the
Sender: header. If there is no Sender: header, it is the first name and
email address in the From: header. If neither header is present,
then an empty Mail::Address object is returned.
.PP
To get just the email address part, do:
.PP
.Vb 1
\&  my $email = $dkim\->message_sender\->address;
.Ve
.PP
The \*(L"sender\*(R" is the mailbox of the agent responsible for the actual
transmission of the message. For example, if a secretary were to send a
message for another person, the \*(L"sender\*(R" would be the secretary and
the \*(L"originator\*(R" would be the actual author.
.SS "\fIpolicies()\fP"
.IX Subsection "policies()"
Retrieves applicable signing policies from \s-1DNS.\s0
.PP
.Vb 6
\&  my @policies = $dkim\->policies;
\&  foreach my $policy (@policies)
\&  {
\&      $policy_result = $policy\->apply($dkim);
\&      # $policy_result is one of "accept", "reject", "neutral"
\&  }
.Ve
.PP
This method searches for and returns any signing policies that would
apply to this message. Signing policies are selected based on the
domain that the message *claims* to be from. So, for example, if
a message claims to be from security@bank, and forwarded by
trusted@listserv, when in reality the message came from foe@evilcorp,
this method would check for signing policies for security@bank and
trusted@listserv. The signing policies might tell whether
foe@evilcorp (the real sender) is allowed to send mail claiming
to be from your bank or your listserv.
.PP
I say \*(L"might tell\*(R", because in reality this is still really hard to
specify with any accuracy. In addition, most senders do not publish
useful policies.
.SS "\fIresult()\fP"
.IX Subsection "result()"
Access the result of the verification.
.PP
.Vb 1
\&  my $result = $dkim\->result;
.Ve
.PP
Gives the result of the verification. The following values are possible:
.IP "pass" 4
.IX Item "pass"
Returned if a valid DKIM-Signature header was found, and the signature
contains a correct value for the message.
.IP "fail" 4
.IX Item "fail"
Returned if a valid DKIM-Signature header was found, but the signature
does not contain a correct value for the message.
.IP "invalid" 4
.IX Item "invalid"
Returned if a DKIM-Signature could not be checked because of a problem
in the signature itself or the public key record. I.e. the signature
could not be processed.
.IP "temperror" 4
.IX Item "temperror"
Returned if a DKIM-Signature could not be checked due to some error
which is likely transient in nature, such as a temporary inability
to retrieve a public key. A later attempt may produce a better
result.
.IP "none" 4
.IX Item "none"
Returned if no DKIM-Signature headers (valid or invalid) were found.
.PP
In case of multiple signatures, the \*(L"best\*(R" result will be returned.
Best is defined as \*(L"pass\*(R", followed by \*(L"fail\*(R", \*(L"invalid\*(R", and \*(L"none\*(R".
To examine the results of individual signatures, use the \*(L"\fIsignatures()\fR\*(R"
method to retrieve the signature objects. See
\&\*(L"\fIresult()\fR\*(R" in Mail::DKIM::Signature.
.SS "\fIresult_detail()\fP"
.IX Subsection "result_detail()"
Access the result, plus details if available.
.PP
.Vb 1
\&  my $detail = $dkim\->result_detail;
.Ve
.PP
The detail is constructed by taking the result (e.g. \*(L"pass\*(R", \*(L"fail\*(R",
\&\*(L"invalid\*(R" or \*(L"none\*(R") and appending any details provided by the verification
process in parenthesis.
.PP
The following are possible results from the \fIresult_detail()\fR method:
.PP
.Vb 10
\&  pass
\&  fail (bad RSA signature)
\&  fail (OpenSSL error: ...)
\&  fail (message has been altered)
\&  fail (body has been altered)
\&  invalid (bad identity)
\&  invalid (invalid domain in d tag)
\&  invalid (missing q tag)
\&  invalid (missing d tag)
\&  invalid (missing s tag)
\&  invalid (unsupported version 0.1)
\&  invalid (unsupported algorithm ...)
\&  invalid (unsupported canonicalization ...)
\&  invalid (unsupported query protocol ...)
\&  invalid (signature is expired)
\&  invalid (public key: not available)
\&  invalid (public key: unknown query type ...)
\&  invalid (public key: syntax error)
\&  invalid (public key: unsupported version)
\&  invalid (public key: unsupported key type)
\&  invalid (public key: missing p= tag)
\&  invalid (public key: invalid data)
\&  invalid (public key: does not support email)
\&  invalid (public key: does not support hash algorithm \*(Aqsha1\*(Aq)
\&  invalid (public key: does not support signing subdomains)
\&  invalid (public key: revoked)
\&  invalid (public key: granularity mismatch)
\&  invalid (public key: granularity is empty)
\&  invalid (public key: OpenSSL error: ...)
\&  none
.Ve
.SS "\fIsignature()\fP"
.IX Subsection "signature()"
Access the message's \s-1DKIM\s0 signature.
.PP
.Vb 1
\&  my $sig = $dkim\->signature;
.Ve
.PP
Accesses the signature found and verified in this message. The returned
object is of type Mail::DKIM::Signature.
.PP
In case of multiple signatures, the signature with the \*(L"best\*(R" result will
be returned.
Best is defined as \*(L"pass\*(R", followed by \*(L"fail\*(R", \*(L"invalid\*(R", and \*(L"none\*(R".
.SS "\fIsignatures()\fP"
.IX Subsection "signatures()"
Access all of this message's signatures.
.PP
.Vb 1
\&  my @all_signatures = $dkim\->signatures;
.Ve
.PP
Use \f(CW$signature\fR\->result or \f(CW$signature\fR\->result_detail to access
the verification results of each signature.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jason Long, <jlong@messiah.edu>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006\-2009 by Messiah College
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.