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 CLOSE()
98 Call this when finished feeding in the message.
99 $dkim->CLOSE;
101 This method finishes the canonicalization process, computes a hash, and
103 verifies the signature.
104 fetch_author_domain_policies()
106 Retrieves ADSP records from DNS.
107 my @policies = $dkim->fetch_author_domain_policies;
109 foreach my $policy (@policies)
110 {
111 my $policy_result = $policy->apply($dkim);
112 }
113 This method will retrieve all applicable "author-domain-signing-
115 practices" published in DNS for this message. Author policies are
116 keyed to the email address(es) in the From: header, i.e. the claimed
117 author of the message.
118 This method returns a *list* of policy records, since there is allowed
120 to be zero or multiple email addresses in the From: header.
121 The result of the apply() method is one of: "accept", "reject",
123 "neutral".
124 See also: "policies()".
126 fetch_author_policy()
128 Retrieves a signing policy from DNS.
129 my $policy = $dkim->fetch_author_policy;
131 my $policy_result = $policy->apply($dkim);
132 This method retrieves the DKIM Sender Signing Practices record as
134 described in Internet Draft draft-ietf-dkim-ssp-00-01dc. This Internet
135 Draft is now obsolete; this method is only kept for backward-
136 compatibility purposes.
137 Please use the "policies()" method instead.
139 fetch_sender_policy()
141 Retrieves a signing policy from DNS.
142 my $policy = $dkim->fetch_sender_policy;
144 my $policy_result = $policy->apply($dkim);
145 The "sender" policy is the sender signing policy as described by the
147 DomainKeys specification, now available in RFC4870(historical). I call
148 it the "sender" policy because it is keyed to the email address in the
149 Sender: header, or the From: header if there is no Sender header. This
150 is the person whom the message claims as the "transmitter" of the
151 message (not necessarily the author).
152 If the email being verified has no From or Sender header from which to
154 get an email address (which violates email standards), then this method
155 will "die".
156 The result of the apply() method is one of: "accept", "reject",
158 "neutral".
159 See also: "policies()".
161 load()
163 Load the entire message from a file handle.
164 $dkim->load($file_handle);
166 Reads a complete message from the designated file handle, feeding it
168 into the verifier. The message must use <CRLF> line terminators (same
169 as the SMTP protocol).
170 message_originator()
172 Access the "From" header.
173 my $address = $dkim->message_originator;
175 Returns the "originator address" found in the message, as a
177 Mail::Address object. This is typically the (first) name and email
178 address found in the From: header. If there is no From: header, then an
179 empty Mail::Address object is returned.
180 To get just the email address part, do:
182 my $email = $dkim->message_originator->address;
184 See also "message_sender()".
186 message_sender()
188 Access the "From" or "Sender" header.
189 my $address = $dkim->message_sender;
191 Returns the "sender" found in the message, as a Mail::Address object.
193 This is typically the (first) name and email address found in the
194 Sender: header. If there is no Sender: header, it is the first name and
195 email address in the From: header. If neither header is present, then
196 an empty Mail::Address object is returned.
197 To get just the email address part, do:
199 my $email = $dkim->message_sender->address;
201 The "sender" is the mailbox of the agent responsible for the actual
203 transmission of the message. For example, if a secretary were to send a
204 message for another person, the "sender" would be the secretary and the
205 "originator" would be the actual author.
206 policies()
208 Retrieves applicable signing policies from DNS.
209 my @policies = $dkim->policies;
211 foreach my $policy (@policies)
212 {
213 $policy_result = $policy->apply($dkim);
214 # $policy_result is one of "accept", "reject", "neutral"
215 }
216 This method searches for and returns any signing policies that would
218 apply to this message. Signing policies are selected based on the
219 domain that the message *claims* to be from. So, for example, if a
220 message claims to be from security@bank, and forwarded by
221 trusted@listserv, when in reality the message came from foe@evilcorp,
222 this method would check for signing policies for security@bank and
223 trusted@listserv. The signing policies might tell whether foe@evilcorp
224 (the real sender) is allowed to send mail claiming to be from your bank
225 or your listserv.
226 I say "might tell", because in reality this is still really hard to
228 specify with any accuracy. In addition, most senders do not publish
229 useful policies.
230 result()
232 Access the result of the verification.
233 my $result = $dkim->result;
235 Gives the result of the verification. The following values are
237 possible:
238 pass
240 Returned if a valid DKIM-Signature header was found, and the
241 signature contains a correct value for the message.
242 fail
244 Returned if a valid DKIM-Signature header was found, but the
245 signature does not contain a correct value for the message.
246 invalid
248 Returned if a DKIM-Signature could not be checked because of a
249 problem in the signature itself or the public key record. I.e. the
250 signature could not be processed.
251 temperror
253 Returned if a DKIM-Signature could not be checked due to some error
254 which is likely transient in nature, such as a temporary inability
255 to retrieve a public key. A later attempt may produce a better
256 result.
257 none
259 Returned if no DKIM-Signature headers (valid or invalid) were
260 found.
261 In case of multiple signatures, the "best" result will be returned.
263 Best is defined as "pass", followed by "fail", "invalid", and "none".
264 To examine the results of individual signatures, use the "signatures()"
265 method to retrieve the signature objects. See "result()" in
266 Mail::DKIM::Signature.
267 result_detail()
269 Access the result, plus details if available.
270 my $detail = $dkim->result_detail;
272 The detail is constructed by taking the result (e.g. "pass", "fail",
274 "invalid" or "none") and appending any details provided by the
275 verification process in parenthesis.
276 The following are possible results from the result_detail() method:
278 pass
280 fail (bad RSA signature)
281 fail (OpenSSL error: ...)
282 fail (message has been altered)
283 fail (body has been altered)
284 invalid (bad identity)
285 invalid (invalid domain in d tag)
286 invalid (missing q tag)
287 invalid (missing d tag)
288 invalid (missing s tag)
289 invalid (unsupported version 0.1)
290 invalid (unsupported algorithm ...)
291 invalid (unsupported canonicalization ...)
292 invalid (unsupported query protocol ...)
293 invalid (signature is expired)
294 invalid (public key: not available)
295 invalid (public key: unknown query type ...)
296 invalid (public key: syntax error)
297 invalid (public key: unsupported version)
298 invalid (public key: unsupported key type)
299 invalid (public key: missing p= tag)
300 invalid (public key: invalid data)
301 invalid (public key: does not support email)
302 invalid (public key: does not support hash algorithm 'sha1')
303 invalid (public key: does not support signing subdomains)
304 invalid (public key: revoked)
305 invalid (public key: granularity mismatch)
306 invalid (public key: granularity is empty)
307 invalid (public key: OpenSSL error: ...)
308 none
309 signature()
311 Access the message's DKIM signature.
312 my $sig = $dkim->signature;
314 Accesses the signature found and verified in this message. The returned
316 object is of type Mail::DKIM::Signature.
317 In case of multiple signatures, the signature with the "best" result
319 will be returned. Best is defined as "pass", followed by "fail",
320 "invalid", and "none".
321 signatures()
323 Access all of this message's signatures.
324 my @all_signatures = $dkim->signatures;
326 Use $signature->result or $signature->result_detail to access the
328 verification results of each signature.
329
331 Jason Long, <jlong@messiah.edu>
332
334 Copyright (C) 2006-2009 by Messiah College
335 This library is free software; you can redistribute it and/or modify it
337 under the same terms as Perl itself, either Perl version 5.8.6 or, at
338 your option, any later version of Perl 5 you may have available.
339perl v5.10.1 2009-07-30 Mail::DKIM::Verifier(3)