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, incrementally
  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;

DESCRIPTION

The verifier object allows an email message to be scanned for DKIM 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.

To use the verifier, first create the verifier object. Then start "feeding" it the email message to be verified. When all the headers have been read, the verifier:

 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

Then, when the body of the message has been completely fed into the verifier, the body hash is computed and the signatures are verified.

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");
  $dkim->PRINT("more of");
  $dkim->PRINT(" the message\015\012bye\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 a signing policy from DNS

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

The "author" policy, as I call it, is the DKIM Sender Signing Practices record as described in Internet Draft draft-ietf-dkim-ssp-00-01dc. I call it the "author" policy because it is keyed to the email address in the From: header, i.e. the author of the message.

The IETF is still actively working on this Internet Draft, so the exact mechanisms are subject to change.

If the email being verified has no From header at all (which violates email standards), then this method will die.

The result of the apply() method is one of: "accept", "reject", "neutral".

fetch_sender_policy() - retrieves a signing policy from DNS

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

The "sender" policy is the sender signing policy as described by the DomainKeys specification, now available in RFC4870(historical). I call it the "sender" 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 "transmitter" of the message (not necessarily the author).

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 die.

The result of the apply() method is one of: "accept", "reject", "neutral".

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, 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.

To get just the email address part, do:

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

See also /"message_sender()".

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

  my $address = $dkim->message_sender;

Returns the "sender" 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.

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 a DKIM-Signature could not be checked because of a problem in the signature itself or the public key record.
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 (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 'sha1')
  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

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".

signatures() - access all of this message's signatures

  my @all_signatures = $dkim->signatures;

Use $signature->result or $signature->result_detail to access the verification results of each signature. =cut

sub signatures { my $self = shift; croak "unexpected argument" if @_;

	return @{$self->{signatures}};
}

AUTHOR

Jason Long, <jlong@messiah.edu>

COPYRIGHT AND LICENSE

Copyright (C) 2006-2007 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.