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 option supported at this time is:
80 Debug_Canonicalization
82 if specified, the canonicalized message for the first signature is
83 written to the referenced string or file handle.
84
86 PRINT()
87 Feeds part of the message to the verifier.
88 $dkim->PRINT("a line of the message\015\012");
90 $dkim->PRINT("more of");
91 $dkim->PRINT(" the message\015\012bye\015\012");
92 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 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 CLOSE()
103 Call this when finished feeding in the message.
104 $dkim->CLOSE;
106 This method finishes the canonicalization process, computes a hash, and
108 verifies the signature.
109 fetch_author_domain_policies()
111 Retrieves ADSP records from DNS.
112 my @policies = $dkim->fetch_author_domain_policies;
114 foreach my $policy (@policies)
115 {
116 my $policy_result = $policy->apply($dkim);
117 }
118 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 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 The result of the apply() method is one of: "accept", "reject",
128 "neutral".
129 See also: "policies()".
131 fetch_author_policy()
133 Retrieves a signing policy from DNS.
134 my $policy = $dkim->fetch_author_policy;
136 my $policy_result = $policy->apply($dkim);
137 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 Please use the "policies()" method instead.
144 fetch_sender_policy()
146 Retrieves a signing policy from DNS.
147 my $policy = $dkim->fetch_sender_policy;
149 my $policy_result = $policy->apply($dkim);
150 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 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 The result of the apply() method is one of: "accept", "reject",
163 "neutral".
164 See also: "policies()".
166 load()
168 Load the entire message from a file handle.
169 $dkim->load($file_handle);
171 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 message_originator()
177 Access the "From" header.
178 my $address = $dkim->message_originator;
180 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 To get just the email address part, do:
187 my $email = $dkim->message_originator->address;
189 See also "message_sender()".
191 message_sender()
193 Access the "From" or "Sender" header.
194 my $address = $dkim->message_sender;
196 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 To get just the email address part, do:
204 my $email = $dkim->message_sender->address;
206 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 policies()
213 Retrieves applicable signing policies from DNS.
214 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 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 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 result()
237 Access the result of the verification.
238 my $result = $dkim->result;
240 Gives the result of the verification. The following values are
242 possible:
243 pass
245 Returned if a valid DKIM-Signature header was found, and the
246 signature contains a correct value for the message.
247 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 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 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 none
264 Returned if no DKIM-Signature headers (valid or invalid) were
265 found.
266 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 result_detail()
274 Access the result, plus details if available.
275 my $detail = $dkim->result_detail;
277 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 The following are possible results from the result_detail() method:
283 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 signature()
316 Access the message's DKIM signature.
317 my $sig = $dkim->signature;
319 Accesses the signature found and verified in this message. The returned
321 object is of type Mail::DKIM::Signature.
322 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 signatures()
328 Access all of this message's signatures.
329 my @all_signatures = $dkim->signatures;
331 Use $signature->result or $signature->result_detail to access the
333 verification results of each signature.
334
336 Jason Long, <jlong@messiah.edu>
337
339 Copyright (C) 2006-2009 by Messiah College
340 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.
344perl v5.16.3 2010-11-14 Mail::DKIM::Verifier(3)