1Mail::DKIM::Verifier(3)User Contributed Perl DocumentatioMnail::DKIM::Verifier(3)
2
6 Mail::DKIM::Verifier - verifies a DKIM-signed message
7
9 version 1.20220520
10
12 use Mail::DKIM::Verifier;
13 # create a verifier object
15 my $dkim = Mail::DKIM::Verifier->new();
16 # read an email from a file handle
18 $dkim->load(*STDIN);
19 # 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 # use SMTP line terminators
28 $dkim->PRINT("$_\015\012");
29 }
30 $dkim->CLOSE;
31 # what is the result of the verify?
33 my $result = $dkim->result;
34 # 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 # 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
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 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 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 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 The results of the verification can be checked with "result()" or
68 "signatures()".
69 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
75 new()
76 Constructs an object-oriented verifier.
77 my $dkim = Mail::DKIM::Verifier->new();
79 my $dkim = Mail::DKIM::Verifier->new(%options);
81 The only options supported at this time are:
83 Debug_Canonicalization
85 if specified, the canonicalized message for the first signature is
86 written to the referenced string or file handle.
87 Strict
89 If true, rejects sha1 hashes and signing keys shorter than 1024
90 bits.
91
93 PRINT()
94 Feeds part of the message to the verifier.
95 $dkim->PRINT("a line of the message\015\012");
97 $dkim->PRINT('more of');
98 $dkim->PRINT(" the message\015\012bye\015\012");
99 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 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 CLOSE()
110 Call this when finished feeding in the message.
111 $dkim->CLOSE;
113 This method finishes the canonicalization process, computes a hash, and
115 verifies the signature.
116 fetch_author_domain_policies()
118 Retrieves ADSP records from DNS.
119 my @policies = $dkim->fetch_author_domain_policies;
121 foreach my $policy (@policies)
122 {
123 my $policy_result = $policy->apply($dkim);
124 }
125 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 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 The result of the apply() method is one of: "accept", "reject",
135 "neutral".
136 See also: "policies()".
138 fetch_author_policy()
140 Retrieves a signing policy from DNS.
141 my $policy = $dkim->fetch_author_policy;
143 my $policy_result = $policy->apply($dkim);
144 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 Please use the "policies()" method instead.
151 fetch_sender_policy()
153 Retrieves a signing policy from DNS.
154 my $policy = $dkim->fetch_sender_policy;
156 my $policy_result = $policy->apply($dkim);
157 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 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 The result of the apply() method is one of: "accept", "reject",
170 "neutral".
171 See also: "policies()".
173 load()
175 Load the entire message from a file handle.
176 $dkim->load($file_handle);
178 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 message_originator()
184 Access the "From" header.
185 my $address = $dkim->message_originator;
187 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 To get just the email address part, do:
194 my $email = $dkim->message_originator->address;
196 See also "message_sender()".
198 message_sender()
200 Access the "From" or "Sender" header.
201 my $address = $dkim->message_sender;
203 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 To get just the email address part, do:
211 my $email = $dkim->message_sender->address;
213 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 policies()
220 Retrieves applicable signing policies from DNS.
221 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 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 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 result()
244 Access the result of the verification.
245 my $result = $dkim->result;
247 Gives the result of the verification. The following values are
249 possible:
250 pass
252 Returned if a valid DKIM-Signature header was found, and the
253 signature contains a correct value for the message.
254 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 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 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 none
271 Returned if no DKIM-Signature headers (valid or invalid) were
272 found.
273 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 result_detail()
281 Access the result, plus details if available.
282 my $detail = $dkim->result_detail;
284 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 The following are possible results from the result_detail() method:
290 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 signature()
323 Access the message's DKIM signature.
324 my $sig = $dkim->signature;
326 Accesses the signature found and verified in this message. The returned
328 object is of type Mail::DKIM::Signature.
329 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 signatures()
335 Access all of this message's signatures.
336 my @all_signatures = $dkim->signatures;
338 Use $signature->result or $signature->result_detail to access the
340 verification results of each signature.
341
343 • Jason Long <jason@long.name>
344 • Marc Bradshaw <marc@marcbradshaw.net>
346 • Bron Gondwana <brong@fastmailteam.com> (ARC)
348
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 • Copyright (C) 2010 by Jason Long
357 • Copyright (C) 2017 by Standcore LLC
359 • Copyright (C) 2020 by FastMail Pty Ltd
361 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.
365perl v5.36.0 2023-01-20 Mail::DKIM::Verifier(3)