1Mail::DKIM::Verifier(3)User Contributed Perl DocumentatioMnail::DKIM::Verifier(3)
2
6 Mail::DKIM::Verifier - verifies a DKIM-signed message
7
9 use Mail::DKIM::Verifier;
10 # create a verifier object
12 my $dkim = Mail::DKIM::Verifier->new();
13 # read an email from a file handle
15 $dkim->load(*STDIN);
16 # 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 # use SMTP line terminators
25 $dkim->PRINT("$_\015\012");
26 }
27 $dkim->CLOSE;
28 # what is the result of the verify?
30 my $result = $dkim->result;
31 # 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 # 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
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 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 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 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 The results of the verification can be checked with "result()" or
65 "signatures()".
66 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
72 new()
73 Constructs an object-oriented verifier.
74 my $dkim = Mail::DKIM::Verifier->new();
76 my $dkim = Mail::DKIM::Verifier->new(%options);
78 The only options supported at this time are:
80 Debug_Canonicalization
82 if specified, the canonicalized message for the first signature is
83 written to the referenced string or file handle.
84 Strict
86 If true, rejects sha1 hashes and signing keys shorter than 1024
87 bits.
88
90 PRINT()
91 Feeds part of the message to the verifier.
92 $dkim->PRINT("a line of the message\015\012");
94 $dkim->PRINT('more of');
95 $dkim->PRINT(" the message\015\012bye\015\012");
96 Feeds content of the message being verified into the verifier. The API
98 is designed this way so that the entire message does NOT need to be
99 read into memory at once.
100 Please note that although the PRINT() method expects you to use SMTP-
102 style line termination characters, you should NOT use the SMTP-style
103 dot-stuffing technique described in RFC 2821 section 4.5.2. Nor should
104 you use a <CR><LF>.<CR><LF> sequence to terminate the message.
105 CLOSE()
107 Call this when finished feeding in the message.
108 $dkim->CLOSE;
110 This method finishes the canonicalization process, computes a hash, and
112 verifies the signature.
113 fetch_author_domain_policies()
115 Retrieves ADSP records from DNS.
116 my @policies = $dkim->fetch_author_domain_policies;
118 foreach my $policy (@policies)
119 {
120 my $policy_result = $policy->apply($dkim);
121 }
122 This method will retrieve all applicable "author-domain-signing-
124 practices" published in DNS for this message. Author policies are
125 keyed to the email address(es) in the From: header, i.e. the claimed
126 author of the message.
127 This method returns a *list* of policy records, since there is allowed
129 to be zero or multiple email addresses in the From: header.
130 The result of the apply() method is one of: "accept", "reject",
132 "neutral".
133 See also: "policies()".
135 fetch_author_policy()
137 Retrieves a signing policy from DNS.
138 my $policy = $dkim->fetch_author_policy;
140 my $policy_result = $policy->apply($dkim);
141 This method retrieves the DKIM Sender Signing Practices record as
143 described in Internet Draft draft-ietf-dkim-ssp-00-01dc. This Internet
144 Draft is now obsolete; this method is only kept for backward-
145 compatibility purposes.
146 Please use the "policies()" method instead.
148 fetch_sender_policy()
150 Retrieves a signing policy from DNS.
151 my $policy = $dkim->fetch_sender_policy;
153 my $policy_result = $policy->apply($dkim);
154 The "sender" policy is the sender signing policy as described by the
156 DomainKeys specification, now available in RFC4870(historical). I call
157 it the "sender" policy because it is keyed to the email address in the
158 Sender: header, or the From: header if there is no Sender header. This
159 is the person whom the message claims as the "transmitter" of the
160 message (not necessarily the author).
161 If the email being verified has no From or Sender header from which to
163 get an email address (which violates email standards), then this method
164 will "die".
165 The result of the apply() method is one of: "accept", "reject",
167 "neutral".
168 See also: "policies()".
170 load()
172 Load the entire message from a file handle.
173 $dkim->load($file_handle);
175 Reads a complete message from the designated file handle, feeding it
177 into the verifier. The message must use <CRLF> line terminators (same
178 as the SMTP protocol).
179 message_originator()
181 Access the "From" header.
182 my $address = $dkim->message_originator;
184 Returns the "originator address" found in the message, as a
186 Mail::Address object. This is typically the (first) name and email
187 address found in the From: header. If there is no From: header, then an
188 empty Mail::Address object is returned.
189 To get just the email address part, do:
191 my $email = $dkim->message_originator->address;
193 See also "message_sender()".
195 message_sender()
197 Access the "From" or "Sender" header.
198 my $address = $dkim->message_sender;
200 Returns the "sender" found in the message, as a Mail::Address object.
202 This is typically the (first) name and email address found in the
203 Sender: header. If there is no Sender: header, it is the first name and
204 email address in the From: header. If neither header is present, then
205 an empty Mail::Address object is returned.
206 To get just the email address part, do:
208 my $email = $dkim->message_sender->address;
210 The "sender" is the mailbox of the agent responsible for the actual
212 transmission of the message. For example, if a secretary were to send a
213 message for another person, the "sender" would be the secretary and the
214 "originator" would be the actual author.
215 policies()
217 Retrieves applicable signing policies from DNS.
218 my @policies = $dkim->policies;
220 foreach my $policy (@policies)
221 {
222 $policy_result = $policy->apply($dkim);
223 # $policy_result is one of "accept", "reject", "neutral"
224 }
225 This method searches for and returns any signing policies that would
227 apply to this message. Signing policies are selected based on the
228 domain that the message *claims* to be from. So, for example, if a
229 message claims to be from security@bank, and forwarded by
230 trusted@listserv, when in reality the message came from foe@evilcorp,
231 this method would check for signing policies for security@bank and
232 trusted@listserv. The signing policies might tell whether foe@evilcorp
233 (the real sender) is allowed to send mail claiming to be from your bank
234 or your listserv.
235 I say "might tell", because in reality this is still really hard to
237 specify with any accuracy. In addition, most senders do not publish
238 useful policies.
239 result()
241 Access the result of the verification.
242 my $result = $dkim->result;
244 Gives the result of the verification. The following values are
246 possible:
247 pass
249 Returned if a valid DKIM-Signature header was found, and the
250 signature contains a correct value for the message.
251 fail
253 Returned if a valid DKIM-Signature header was found, but the
254 signature does not contain a correct value for the message.
255 invalid
257 Returned if a DKIM-Signature could not be checked because of a
258 problem in the signature itself or the public key record. I.e. the
259 signature could not be processed.
260 temperror
262 Returned if a DKIM-Signature could not be checked due to some error
263 which is likely transient in nature, such as a temporary inability
264 to retrieve a public key. A later attempt may produce a better
265 result.
266 none
268 Returned if no DKIM-Signature headers (valid or invalid) were
269 found.
270 In case of multiple signatures, the "best" result will be returned.
272 Best is defined as "pass", followed by "fail", "invalid", and "none".
273 To examine the results of individual signatures, use the "signatures()"
274 method to retrieve the signature objects. See "result()" in
275 Mail::DKIM::Signature.
276 result_detail()
278 Access the result, plus details if available.
279 my $detail = $dkim->result_detail;
281 The detail is constructed by taking the result (e.g. "pass", "fail",
283 "invalid" or "none") and appending any details provided by the
284 verification process in parenthesis.
285 The following are possible results from the result_detail() method:
287 pass
289 fail (bad RSA signature)
290 fail (OpenSSL error: ...)
291 fail (message has been altered)
292 fail (body has been altered)
293 invalid (bad identity)
294 invalid (invalid domain in d tag)
295 invalid (missing q tag)
296 invalid (missing d tag)
297 invalid (missing s tag)
298 invalid (unsupported version 0.1)
299 invalid (unsupported algorithm ...)
300 invalid (unsupported canonicalization ...)
301 invalid (unsupported query protocol ...)
302 invalid (signature is expired)
303 invalid (public key: not available)
304 invalid (public key: unknown query type ...)
305 invalid (public key: syntax error)
306 invalid (public key: unsupported version)
307 invalid (public key: unsupported key type)
308 invalid (public key: missing p= tag)
309 invalid (public key: invalid data)
310 invalid (public key: does not support email)
311 invalid (public key: does not support hash algorithm 'sha1')
312 invalid (public key: does not support signing subdomains)
313 invalid (public key: revoked)
314 invalid (public key: granularity mismatch)
315 invalid (public key: granularity is empty)
316 invalid (public key: OpenSSL error: ...)
317 none
318 signature()
320 Access the message's DKIM signature.
321 my $sig = $dkim->signature;
323 Accesses the signature found and verified in this message. The returned
325 object is of type Mail::DKIM::Signature.
326 In case of multiple signatures, the signature with the "best" result
328 will be returned. Best is defined as "pass", followed by "fail",
329 "invalid", and "none".
330 signatures()
332 Access all of this message's signatures.
333 my @all_signatures = $dkim->signatures;
335 Use $signature->result or $signature->result_detail to access the
337 verification results of each signature.
338
340 Jason Long, <jlong@messiah.edu>
341
343 Copyright (C) 2006-2009 by Messiah College
344 This library is free software; you can redistribute it and/or modify it
346 under the same terms as Perl itself, either Perl version 5.8.6 or, at
347 your option, any later version of Perl 5 you may have available.
348
350 Hey! The above document had some coding errors, which are explained
351 below:
352 Around line 109:
354 '=item' outside of any '=over'
355perl v5.30.0 2019-07-26 Mail::DKIM::Verifier(3)