/ 
Mail-DKIM-0.22
River stage one • 3 direct dependents • 7 total dependents
/ Mail::DKIM::Verifier

NAME

Mail::DKIM::Verifier - verifies a DKIM-signed message

SYNOPSIS

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, one line at a time
while (<STDIN>)
{
    # remove local line terminators
    chomp;
    s/\015$//;

    # use SMTP line terminators
    $dkim->PRINT("$_\015\012");
}
$dkim->CLOSE;

# what is the result of the verify?
my $result = $dkim->result;

CONSTRUCTOR

new() - construct an object-oriented verifier

my $dkim = Mail::DKIM::Verifier->new();

my $dkim = Mail::DKIM::Verifier->new(%options);

The only option supported at this time is:

Debug_Canonicalization

if specified, the canonicalized message for the first signature is written to the referenced string or file handle.

METHODS

PRINT() - feed part of the message to the verifier

$dkim->PRINT("a line of the message\015\012");

Feeds content of the message being verified into the verifier. The API is designed this way so that the entire message does NOT need to be read into memory at once.

CLOSE() - call this when finished feeding in the message

$dkim->CLOSE;

This method finishes the canonicalization process, computes a hash, and verifies the signature.

fetch_author_policy() - retrieves the "sender signing policy" from DNS

my $policy = $dkim->fetch_author_policy;
my $policy_result = $policy->apply($dkim);

See also the fetch() method of Mail::DKIM::Policy.

The "author" policy is the policy for the address found in the From header, i.e. the "originator" address.

The result will be undef is there are no headers (i.e. From header) to indicate what policy to check.

load() - load the entire message from a file handle

$dkim->load($file_handle);

Reads a complete message from the designated file handle, feeding it into the verifier. The message must use <CRLF> line terminators (same as the SMTP protocol).

message_originator() - access the "From" header

my $address = $dkim->message_originator;

Returns the "originator address" found in the message. This is typically the (first) name and email address found in the From: header. The returned object is of type Mail::Address. To get just the email address part, do:

my $email = $dkim->message_originator->address;

message_sender() - access the "From" or "Sender" header

my $address = $dkim->message_sender;

Returns the "sender" found in the message. 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. The returned object is of type Mail::Address, so to get just the email address part, do:

my $email = $dkim->message_sender->address;

The "sender" 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 "sender" would be the secretary and the "originator" would be the actual author.

result() - access the result of the verification

my $result = $dkim->result;

Gives the result of the verification. The following values are possible:

pass

Returned if a valid DKIM-Signature header was found, and the signature contains a correct value for the message.

fail

Returned if a valid DKIM-Signature header was found, but the signature does not contain a correct value for the message.

invalid

Returned if no valid DKIM-Signature headers were found, but there is at least one invalid DKIM-Signature header. For a reason why a DKIM-Signature header found in the message was invalid, see $dkim->{signature_reject_reason}.

none

Returned if no DKIM-Signature headers (valid or invalid) were found.

In case of multiple signatures, the "best" result will be returned. Best is defined as "pass", followed by "fail", "invalid", and "none".

result_detail() - access the result, plus details if available

my $detail = $dkim->result_detail;

The detail is constructed by taking the result (i.e. one of "pass", "fail", "invalid" or "none") and appending any details provided by the verification process in parenthesis.

The following are possible results from the result_detail() method:

pass
fail (bad RSA signature)
fail (headers have been altered)
fail (body has been altered)
invalid (unsupported canonicalization)
invalid (unsupported protocol)
invalid (missing d= parameter)
invalid (missing s= parameter)
invalid (unsupported v=0.1 tag)
invalid (no public key available)
invalid (public key has been revoked)
none

signature() - access the message's DKIM signature

my $sig = $dkim->signature;

Accesses the signature found and verified in this message. The returned object is of type Mail::DKIM::Signature.

In case of multiple signatures, the signature with the "best" result will be returned. Best is defined as "pass", followed by "fail", "invalid", and "none".

AUTHOR

Jason Long, <jlong@messiah.edu>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Messiah College

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.