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

VERSION

9       version 1.20220520
10

SYNOPSIS

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

DESCRIPTION

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

CONSTRUCTOR

75   new()
76       Constructs an object-oriented verifier.
77
78         my $dkim = Mail::DKIM::Verifier->new();
79
80         my $dkim = Mail::DKIM::Verifier->new(%options);
81
82       The only options supported at this time are:
83
84       Debug_Canonicalization
85           if specified, the canonicalized message for the first signature is
86           written to the referenced string or file handle.
87
88       Strict
89           If true, rejects sha1 hashes and signing keys shorter than 1024
90           bits.
91

METHODS

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

AUTHORS

343       •   Jason Long <jason@long.name>
344
345       •   Marc Bradshaw <marc@marcbradshaw.net>
346
347       •   Bron Gondwana <brong@fastmailteam.com> (ARC)
348

THANKS

350       Work on ensuring that this module passes the ARC test suite was
351       generously sponsored by Valimail (https://www.valimail.com/)
352
354       •   Copyright (C) 2013 by Messiah College
355
356       •   Copyright (C) 2010 by Jason Long
357
358       •   Copyright (C) 2017 by Standcore LLC
359
360       •   Copyright (C) 2020 by FastMail Pty Ltd
361
362       This library is free software; you can redistribute it and/or modify it
363       under the same terms as Perl itself, either Perl version 5.8.6 or, at
364       your option, any later version of Perl 5 you may have available.
365
366
367
368perl v5.36.0                      2022-07-22           Mail::DKIM::Verifier(3)
Impressum