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

SYNOPSIS

9         use Mail::DKIM::Verifier;
10
11         # create a verifier object
12         my $dkim = Mail::DKIM::Verifier->new();
13
14         # read an email from a file handle
15         $dkim->load(*STDIN);
16
17         # 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
24             # use SMTP line terminators
25             $dkim->PRINT("$_\015\012");
26         }
27         $dkim->CLOSE;
28
29         # what is the result of the verify?
30         my $result = $dkim->result;
31
32         # 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
39         # 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

DESCRIPTION

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
52       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
56        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
61       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
64       The results of the verification can be checked with "result()" or
65       "signatures()".
66
67       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

CONSTRUCTOR

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

METHODS

90   PRINT()
91       Feeds part of the message to the verifier.
92
93         $dkim->PRINT("a line of the message\015\012");
94         $dkim->PRINT('more of');
95         $dkim->PRINT(" the message\015\012bye\015\012");
96
97       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
101       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
106   CLOSE()
107       Call this when finished feeding in the message.
108
109         $dkim->CLOSE;
110
111       This method finishes the canonicalization process, computes a hash, and
112       verifies the signature.
113
114   fetch_author_domain_policies()
115       Retrieves ADSP records from DNS.
116
117         my @policies = $dkim->fetch_author_domain_policies;
118         foreach my $policy (@policies)
119         {
120             my $policy_result = $policy->apply($dkim);
121         }
122
123       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
128       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
131       The result of the apply() method is one of: "accept", "reject",
132       "neutral".
133
134       See also: "policies()".
135
136   fetch_author_policy()
137       Retrieves a signing policy from DNS.
138
139         my $policy = $dkim->fetch_author_policy;
140         my $policy_result = $policy->apply($dkim);
141
142       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
147       Please use the "policies()" method instead.
148
149   fetch_sender_policy()
150       Retrieves a signing policy from DNS.
151
152         my $policy = $dkim->fetch_sender_policy;
153         my $policy_result = $policy->apply($dkim);
154
155       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
162       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
166       The result of the apply() method is one of: "accept", "reject",
167       "neutral".
168
169       See also: "policies()".
170
171   load()
172       Load the entire message from a file handle.
173
174         $dkim->load($file_handle);
175
176       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
180   message_originator()
181       Access the "From" header.
182
183         my $address = $dkim->message_originator;
184
185       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
190       To get just the email address part, do:
191
192         my $email = $dkim->message_originator->address;
193
194       See also "message_sender()".
195
196   message_sender()
197       Access the "From" or "Sender" header.
198
199         my $address = $dkim->message_sender;
200
201       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
207       To get just the email address part, do:
208
209         my $email = $dkim->message_sender->address;
210
211       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
216   policies()
217       Retrieves applicable signing policies from DNS.
218
219         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
226       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
236       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
240   result()
241       Access the result of the verification.
242
243         my $result = $dkim->result;
244
245       Gives the result of the verification. The following values are
246       possible:
247
248       pass
249           Returned if a valid DKIM-Signature header was found, and the
250           signature contains a correct value for the message.
251
252       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
256       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
261       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
267       none
268           Returned if no DKIM-Signature headers (valid or invalid) were
269           found.
270
271       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
277   result_detail()
278       Access the result, plus details if available.
279
280         my $detail = $dkim->result_detail;
281
282       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
286       The following are possible results from the result_detail() method:
287
288         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
319   signature()
320       Access the message's DKIM signature.
321
322         my $sig = $dkim->signature;
323
324       Accesses the signature found and verified in this message. The returned
325       object is of type Mail::DKIM::Signature.
326
327       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
331   signatures()
332       Access all of this message's signatures.
333
334         my @all_signatures = $dkim->signatures;
335
336       Use $signature->result or $signature->result_detail to access the
337       verification results of each signature.
338

AUTHOR

340       Jason Long, <jlong@messiah.edu>
341
343       Copyright (C) 2006-2009 by Messiah College
344
345       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
349
350
351perl v5.30.1                      2020-01-30           Mail::DKIM::Verifier(3)
Impressum