1Mail::DKIM::ARC::VerifiUesre(r3)Contributed Perl DocumenMtaaitli:o:nDKIM::ARC::Verifier(3)
2
3
4

NAME

6       Mail::DKIM::ARC::Verifier - verifies an ARC-Sealed message
7

VERSION

9       version 1.20220520
10

SYNOPSIS

12         use Mail::DKIM::ARC::Verifier;
13
14         # create a verifier object
15         my $arc = Mail::DKIM::ARC::Verifier->new();
16
17         # read an email from a file handle
18         $arc->load(*STDIN);
19
20         # 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
27             # use SMTP line terminators
28             $arc->PRINT("$_\015\012");
29         }
30         $arc->CLOSE;
31
32         # what is the result of the verify?
33         my $result = $arc->result;
34
35         # print the results for all the message-signatures and seals on the message
36         foreach my $signature ($arc->signatures)
37         {
38             print $signature->prefix() . ' v=' . $signature->instance .
39                                            ' ' . $signature->result_detail . "\n";
40         }
41
42         # example output.  Note that to pass, only the MOST RECENT ARC-Message-Signature
43         # must match, because other steps may have modified the signature.  What matters
44         # is that all ARC-Seals pass, and the most recent ARC-Message-Signature passes.
45

DESCRIPTION

47       The verifier object allows an email message to be scanned for ARC seals
48       and their associated signatures to be verified. The verifier tracks the
49       state of the message as it is read into memory. When the message has
50       been completely read, the signatures are verified and the results of
51       the verification can be accessed.
52
53       To use the verifier, first create the verifier object. Then start
54       "feeding" it the email message to be verified. When all the _headers_
55       have been read, the verifier:
56
57        1. checks whether any ARC signatures were found
58        2. queries for the public keys needed to verify the signatures
59        3. sets up the appropriate algorithms and canonicalization objects
60        4. canonicalizes the headers and computes the header hash
61
62       Then, when the _body_ of the message has been completely fed into the
63       verifier, the body hash is computed and the signatures are verified.
64
65       The results of the verification can be checked with "result()" or
66       "signatures()".
67
68       The final result is calculated by the algorithm layed out in
69       https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-06 - if ALL
70       ARC-Seal headers pass and the highest index (i=) ARC-Message-Signature
71       passes, then the seal is intact.
72

CONSTRUCTOR

74   new()
75       Constructs an object-oriented verifier.
76
77         my $arc = Mail::DKIM::ARC::Verifier->new();
78
79         my $arc = Mail::DKIM::ARC::Verifier->new(%options);
80
81       The only options supported at this time are:
82
83       AS_Canonicalization
84           if specified, the canonicalized message for the ARC-Seal is written
85           to the referenced string or file handle.
86
87       AMA_Canonicalization
88           if specified, the canonicalized message for the ARC-Message-
89           Signature is written to the referenced string or file handle.
90
91       Strict
92           If true, rejects sha1 hashes and signing keys shorter than 1024
93           bits.
94

METHODS

96   PRINT()
97       Feeds part of the message to the verifier.
98
99         $arc->PRINT("a line of the message\015\012");
100         $arc->PRINT('more of');
101         $arc->PRINT(" the message\015\012bye\015\012");
102
103       Feeds content of the message being verified into the verifier.  The API
104       is designed this way so that the entire message does NOT need to be
105       read into memory at once.
106
107       Please note that although the PRINT() method expects you to use SMTP-
108       style line termination characters, you should NOT use the SMTP-style
109       dot-stuffing technique described in RFC 2821 section 4.5.2.  Nor should
110       you use a <CR><LF>.<CR><LF> sequence to terminate the message.
111
112   CLOSE()
113       Call this when finished feeding in the message.
114
115         $arc->CLOSE;
116
117       This method finishes the canonicalization process, computes a hash, and
118       verifies the signature.
119
120   load()
121       Load the entire message from a file handle.
122
123         $arc->load($file_handle);
124
125       Reads a complete message from the designated file handle, feeding it
126       into the verifier. The message must use <CRLF> line terminators (same
127       as the SMTP protocol).
128
129   message_originator()
130       Access the "From" header.
131
132         my $address = $arc->message_originator;
133
134       Returns the "originator address" found in the message, as a
135       Mail::Address object.  This is typically the (first) name and email
136       address found in the From: header. If there is no From: header, then an
137       empty Mail::Address object is returned.
138
139       To get just the email address part, do:
140
141         my $email = $arc->message_originator->address;
142
143       See also "message_sender()".
144
145   message_sender()
146       Access the "From" or "Sender" header.
147
148         my $address = $arc->message_sender;
149
150       Returns the "sender" found in the message, as a Mail::Address object.
151       This is typically the (first) name and email address found in the
152       Sender: header. If there is no Sender: header, it is the first name and
153       email address in the From: header. If neither header is present, then
154       an empty Mail::Address object is returned.
155
156       To get just the email address part, do:
157
158         my $email = $arc->message_sender->address;
159
160       The "sender" is the mailbox of the agent responsible for the actual
161       transmission of the message. For example, if a secretary were to send a
162       message for another person, the "sender" would be the secretary and the
163       "originator" would be the actual author.
164
165   result()
166       Access the result of the verification.
167
168         my $result = $arc->result;
169
170       Gives the result of the verification. The following values are
171       possible:
172
173       pass
174           Returned if a valid ARC chain was found, with all the ARC-Seals
175           passing, and the most recent (highest index) ARC-Message-Signature
176           passing.
177
178       fail
179           Returned if any ARC-Seal failed, or if the ARC-Message-Signature
180           failed.  Will also be a fail if there is a DNS temporary failure,
181           which is a known flaw in this version of the ARC::Verifier.  Future
182           versions may reject this message outright (4xx) and ask the sender
183           to attempt delivery later to avoid creating a broken chain.  There
184           is no temperror for ARC, as it doesn't make sense to sign a chain
185           with temperror in it or every spammer would just use one of those.
186
187       invalid
188           Returned if a ARC-Seal could not be checked because of a problem in
189           the signature itself or the public key record. I.e. the signature
190           could not be processed.
191
192       none
193           Returned if no ARC-* headers were found.
194
195   result_detail()
196       Access the result, plus details if available.
197
198         my $detail = $dkim->result_detail;
199
200       The detail is constructed by taking the result (e.g. "pass", "fail",
201       "invalid" or "none") and appending any details provided by the
202       verification process for the topmost ARC-Seal in parenthesis.
203
204       The following are possible results from the result_detail() method:
205
206         pass
207         fail (bad RSA signature)
208         fail (OpenSSL error: ...)
209         fail (message has been altered)
210         fail (body has been altered)
211         invalid (bad instance)
212         invalid (invalid domain in d tag)
213         invalid (missing q tag)
214         invalid (missing d tag)
215         invalid (missing s tag)
216         invalid (unsupported version 0.1)
217         invalid (unsupported algorithm ...)
218         invalid (unsupported canonicalization ...)
219         invalid (unsupported query protocol ...)
220         invalid (signature is expired)
221         invalid (public key: not available)
222         invalid (public key: unknown query type ...)
223         invalid (public key: syntax error)
224         invalid (public key: unsupported version)
225         invalid (public key: unsupported key type)
226         invalid (public key: missing p= tag)
227         invalid (public key: invalid data)
228         invalid (public key: does not support email)
229         invalid (public key: does not support hash algorithm 'sha1')
230         invalid (public key: does not support signing subdomains)
231         invalid (public key: revoked)
232         invalid (public key: granularity mismatch)
233         invalid (public key: granularity is empty)
234         invalid (public key: OpenSSL error: ...)
235         none
236
237   signatures()
238       Access all of this message's signatures.
239
240         my @all_signatures = $arc->signatures;
241
242       Use $signature->result or $signature->result_detail to access the
243       verification results of each signature.
244
245       Use $signature->instance and $signature->prefix to find the instance
246       and header-name for each signature.
247

AUTHORS

249       •   Jason Long <jason@long.name>
250
251       •   Marc Bradshaw <marc@marcbradshaw.net>
252
253       •   Bron Gondwana <brong@fastmailteam.com> (ARC)
254

THANKS

256       Work on ensuring that this module passes the ARC test suite was
257       generously sponsored by Valimail (https://www.valimail.com/)
258
260       •   Copyright (C) 2013 by Messiah College
261
262       •   Copyright (C) 2010 by Jason Long
263
264       •   Copyright (C) 2017 by Standcore LLC
265
266       •   Copyright (C) 2020 by FastMail Pty Ltd
267
268       This library is free software; you can redistribute it and/or modify it
269       under the same terms as Perl itself, either Perl version 5.8.6 or, at
270       your option, any later version of Perl 5 you may have available.
271
272
273
274perl v5.36.0                      2022-07-22      Mail::DKIM::ARC::Verifier(3)
Impressum