1Mail::DKIM::Verifier(3)User Contributed Perl DocumentatioMnail::DKIM::Verifier(3)
2
3
4

NAME

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

SYNOPSIS

9         use Mail::DKIM::Verifier;
10
11         # create a verifier object
12         my $dkim = Mail::DKIM::Verifier->new();
13
14         # read an email from a file handle
15         $dkim->load(*STDIN);
16
17         # or read an email and pass it into the verifier, incrementally
18         while (<STDIN>)
19         {
20             # remove local line terminators
21             chomp;
22             s/\015$//;
23
24             # use SMTP line terminators
25             $dkim->PRINT("$_\015\012");
26         }
27         $dkim->CLOSE;
28
29         # what is the result of the verify?
30         my $result = $dkim->result;
31
32         # there might be multiple signatures, what is the result per signature?
33         foreach my $signature ($dkim->signatures)
34         {
35             print "signature identity: " . $signature->identity . "\n";
36             print "verify result: " . $signature->result_detail . "\n";
37         }
38
39         # the alleged author of the email may specify how to handle email
40         foreach my $policy ($dkim->policies)
41         {
42             die "fraudulent message" if ($policy->apply($dkim) eq "reject");
43         }
44

DESCRIPTION

46       The verifier object allows an email message to be scanned for DKIM and
47       DomainKeys signatures and those signatures to be verified. The verifier
48       tracks the state of the message as it is read into memory. When the
49       message has been completely read, the signatures are verified and the
50       results of the verification can be accessed.
51
52       To use the verifier, first create the verifier object. Then start
53       "feeding" it the email message to be verified. When all the _headers_
54       have been read, the verifier:
55
56        1. checks whether any DomainKeys/DKIM signatures were found
57        2. queries for the public keys needed to verify the signatures
58        3. sets up the appropriate algorithms and canonicalization objects
59        4. canonicalizes the headers and computes the header hash
60
61       Then, when the _body_ of the message has been completely fed into the
62       verifier, the body hash is computed and the signatures are verified.
63
64       The results of the verification can be checked with "result()" or
65       "signatures()".
66
67       Messages that do not verify may be checked against the alleged sender's
68       published signing policy with "policies()" and "apply()" in
69       Mail::DKIM::Policy.
70

CONSTRUCTOR

72   new()
73       Constructs an object-oriented verifier.
74
75         my $dkim = Mail::DKIM::Verifier->new();
76
77         my $dkim = Mail::DKIM::Verifier->new(%options);
78
79       The only option supported at this time is:
80
81       Debug_Canonicalization
82           if specified, the canonicalized message for the first signature is
83           written to the referenced string or file handle.
84

METHODS

86   PRINT()
87       Feeds part of the message to the verifier.
88
89         $dkim->PRINT("a line of the message\015\012");
90         $dkim->PRINT("more of");
91         $dkim->PRINT(" the message\015\012bye\015\012");
92
93       Feeds content of the message being verified into the verifier.  The API
94       is designed this way so that the entire message does NOT need to be
95       read into memory at once.
96
97       Please note that although the PRINT() method expects you to use SMTP-
98       style line termination characters, you should NOT use the SMTP-style
99       dot-stuffing technique described in RFC 2821 section 4.5.2.  Nor should
100       you use a <CR><LF>.<CR><LF> sequence to terminate the message.
101
102   CLOSE()
103       Call this when finished feeding in the message.
104
105         $dkim->CLOSE;
106
107       This method finishes the canonicalization process, computes a hash, and
108       verifies the signature.
109
110   fetch_author_domain_policies()
111       Retrieves ADSP records from DNS.
112
113         my @policies = $dkim->fetch_author_domain_policies;
114         foreach my $policy (@policies)
115         {
116             my $policy_result = $policy->apply($dkim);
117         }
118
119       This method will retrieve all applicable "author-domain-signing-
120       practices" published in DNS for this message.  Author policies are
121       keyed to the email address(es) in the From: header, i.e. the claimed
122       author of the message.
123
124       This method returns a *list* of policy records, since there is allowed
125       to be zero or multiple email addresses in the From: header.
126
127       The result of the apply() method is one of: "accept", "reject",
128       "neutral".
129
130       See also: "policies()".
131
132   fetch_author_policy()
133       Retrieves a signing policy from DNS.
134
135         my $policy = $dkim->fetch_author_policy;
136         my $policy_result = $policy->apply($dkim);
137
138       This method retrieves the DKIM Sender Signing Practices record as
139       described in Internet Draft draft-ietf-dkim-ssp-00-01dc.  This Internet
140       Draft is now obsolete; this method is only kept for backward-
141       compatibility purposes.
142
143       Please use the "policies()" method instead.
144
145   fetch_sender_policy()
146       Retrieves a signing policy from DNS.
147
148         my $policy = $dkim->fetch_sender_policy;
149         my $policy_result = $policy->apply($dkim);
150
151       The "sender" policy is the sender signing policy as described by the
152       DomainKeys specification, now available in RFC4870(historical).  I call
153       it the "sender" policy because it is keyed to the email address in the
154       Sender: header, or the From: header if there is no Sender header.  This
155       is the person whom the message claims as the "transmitter" of the
156       message (not necessarily the author).
157
158       If the email being verified has no From or Sender header from which to
159       get an email address (which violates email standards), then this method
160       will "die".
161
162       The result of the apply() method is one of: "accept", "reject",
163       "neutral".
164
165       See also: "policies()".
166
167   load()
168       Load the entire message from a file handle.
169
170         $dkim->load($file_handle);
171
172       Reads a complete message from the designated file handle, feeding it
173       into the verifier. The message must use <CRLF> line terminators (same
174       as the SMTP protocol).
175
176   message_originator()
177       Access the "From" header.
178
179         my $address = $dkim->message_originator;
180
181       Returns the "originator address" found in the message, as a
182       Mail::Address object.  This is typically the (first) name and email
183       address found in the From: header. If there is no From: header, then an
184       empty Mail::Address object is returned.
185
186       To get just the email address part, do:
187
188         my $email = $dkim->message_originator->address;
189
190       See also "message_sender()".
191
192   message_sender()
193       Access the "From" or "Sender" header.
194
195         my $address = $dkim->message_sender;
196
197       Returns the "sender" found in the message, as a Mail::Address object.
198       This is typically the (first) name and email address found in the
199       Sender: header. If there is no Sender: header, it is the first name and
200       email address in the From: header. If neither header is present, then
201       an empty Mail::Address object is returned.
202
203       To get just the email address part, do:
204
205         my $email = $dkim->message_sender->address;
206
207       The "sender" is the mailbox of the agent responsible for the actual
208       transmission of the message. For example, if a secretary were to send a
209       message for another person, the "sender" would be the secretary and the
210       "originator" would be the actual author.
211
212   policies()
213       Retrieves applicable signing policies from DNS.
214
215         my @policies = $dkim->policies;
216         foreach my $policy (@policies)
217         {
218             $policy_result = $policy->apply($dkim);
219             # $policy_result is one of "accept", "reject", "neutral"
220         }
221
222       This method searches for and returns any signing policies that would
223       apply to this message. Signing policies are selected based on the
224       domain that the message *claims* to be from. So, for example, if a
225       message claims to be from security@bank, and forwarded by
226       trusted@listserv, when in reality the message came from foe@evilcorp,
227       this method would check for signing policies for security@bank and
228       trusted@listserv. The signing policies might tell whether foe@evilcorp
229       (the real sender) is allowed to send mail claiming to be from your bank
230       or your listserv.
231
232       I say "might tell", because in reality this is still really hard to
233       specify with any accuracy. In addition, most senders do not publish
234       useful policies.
235
236   result()
237       Access the result of the verification.
238
239         my $result = $dkim->result;
240
241       Gives the result of the verification. The following values are
242       possible:
243
244       pass
245           Returned if a valid DKIM-Signature header was found, and the
246           signature contains a correct value for the message.
247
248       fail
249           Returned if a valid DKIM-Signature header was found, but the
250           signature does not contain a correct value for the message.
251
252       invalid
253           Returned if a DKIM-Signature could not be checked because of a
254           problem in the signature itself or the public key record. I.e. the
255           signature could not be processed.
256
257       temperror
258           Returned if a DKIM-Signature could not be checked due to some error
259           which is likely transient in nature, such as a temporary inability
260           to retrieve a public key. A later attempt may produce a better
261           result.
262
263       none
264           Returned if no DKIM-Signature headers (valid or invalid) were
265           found.
266
267       In case of multiple signatures, the "best" result will be returned.
268       Best is defined as "pass", followed by "fail", "invalid", and "none".
269       To examine the results of individual signatures, use the "signatures()"
270       method to retrieve the signature objects. See "result()" in
271       Mail::DKIM::Signature.
272
273   result_detail()
274       Access the result, plus details if available.
275
276         my $detail = $dkim->result_detail;
277
278       The detail is constructed by taking the result (e.g. "pass", "fail",
279       "invalid" or "none") and appending any details provided by the
280       verification process in parenthesis.
281
282       The following are possible results from the result_detail() method:
283
284         pass
285         fail (bad RSA signature)
286         fail (OpenSSL error: ...)
287         fail (message has been altered)
288         fail (body has been altered)
289         invalid (bad identity)
290         invalid (invalid domain in d tag)
291         invalid (missing q tag)
292         invalid (missing d tag)
293         invalid (missing s tag)
294         invalid (unsupported version 0.1)
295         invalid (unsupported algorithm ...)
296         invalid (unsupported canonicalization ...)
297         invalid (unsupported query protocol ...)
298         invalid (signature is expired)
299         invalid (public key: not available)
300         invalid (public key: unknown query type ...)
301         invalid (public key: syntax error)
302         invalid (public key: unsupported version)
303         invalid (public key: unsupported key type)
304         invalid (public key: missing p= tag)
305         invalid (public key: invalid data)
306         invalid (public key: does not support email)
307         invalid (public key: does not support hash algorithm 'sha1')
308         invalid (public key: does not support signing subdomains)
309         invalid (public key: revoked)
310         invalid (public key: granularity mismatch)
311         invalid (public key: granularity is empty)
312         invalid (public key: OpenSSL error: ...)
313         none
314
315   signature()
316       Access the message's DKIM signature.
317
318         my $sig = $dkim->signature;
319
320       Accesses the signature found and verified in this message. The returned
321       object is of type Mail::DKIM::Signature.
322
323       In case of multiple signatures, the signature with the "best" result
324       will be returned.  Best is defined as "pass", followed by "fail",
325       "invalid", and "none".
326
327   signatures()
328       Access all of this message's signatures.
329
330         my @all_signatures = $dkim->signatures;
331
332       Use $signature->result or $signature->result_detail to access the
333       verification results of each signature.
334

AUTHOR

336       Jason Long, <jlong@messiah.edu>
337
339       Copyright (C) 2006-2009 by Messiah College
340
341       This library is free software; you can redistribute it and/or modify it
342       under the same terms as Perl itself, either Perl version 5.8.6 or, at
343       your option, any later version of Perl 5 you may have available.
344
345
346
347perl v5.12.2                      2010-11-14           Mail::DKIM::Verifier(3)
Impressum