1Mail::DKIM::ARC::VerifiUesre(r3)Contributed Perl DocumenMtaaitli:o:nDKIM::ARC::Verifier(3)
2
6 Mail::DKIM::ARC::Verifier - verifies an ARC-Sealed message
7
9 version 1.20230630
10
12 use Mail::DKIM::ARC::Verifier;
13 # create a verifier object
15 my $arc = Mail::DKIM::ARC::Verifier->new();
16 # read an email from a file handle
18 $arc->load(*STDIN);
19 # 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 # use SMTP line terminators
28 $arc->PRINT("$_\015\012");
29 }
30 $arc->CLOSE;
31 # what is the result of the verify?
33 my $result = $arc->result;
34 # 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 # 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
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 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 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 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 The results of the verification can be checked with "result()" or
66 "signatures()".
67 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
74 new()
75 Constructs an object-oriented verifier.
76 my $arc = Mail::DKIM::ARC::Verifier->new();
78 my $arc = Mail::DKIM::ARC::Verifier->new(%options);
80 The only options supported at this time are:
82 AS_Canonicalization
84 if specified, the canonicalized message for the ARC-Seal is written
85 to the referenced string or file handle.
86 AMA_Canonicalization
88 if specified, the canonicalized message for the ARC-Message-
89 Signature is written to the referenced string or file handle.
90 Strict
92 If true, rejects sha1 hashes and signing keys shorter than 1024
93 bits.
94
96 PRINT()
97 Feeds part of the message to the verifier.
98 $arc->PRINT("a line of the message\015\012");
100 $arc->PRINT('more of');
101 $arc->PRINT(" the message\015\012bye\015\012");
102 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 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 CLOSE()
113 Call this when finished feeding in the message.
114 $arc->CLOSE;
116 This method finishes the canonicalization process, computes a hash, and
118 verifies the signature.
119 load()
121 Load the entire message from a file handle.
122 $arc->load($file_handle);
124 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 message_originator()
130 Access the "From" header.
131 my $address = $arc->message_originator;
133 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 To get just the email address part, do:
140 my $email = $arc->message_originator->address;
142 See also "message_sender()".
144 message_sender()
146 Access the "From" or "Sender" header.
147 my $address = $arc->message_sender;
149 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 To get just the email address part, do:
157 my $email = $arc->message_sender->address;
159 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 result()
166 Access the result of the verification.
167 my $result = $arc->result;
169 Gives the result of the verification. The following values are
171 possible:
172 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 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 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 none
193 Returned if no ARC-* headers were found.
194 result_detail()
196 Access the result, plus details if available.
197 my $detail = $dkim->result_detail;
199 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 The following are possible results from the result_detail() method:
205 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 signatures()
238 Access all of this message's signatures.
239 my @all_signatures = $arc->signatures;
241 Use $signature->result or $signature->result_detail to access the
243 verification results of each signature.
244 Use $signature->instance and $signature->prefix to find the instance
246 and header-name for each signature.
247
249 • Jason Long <jason@long.name>
250 • Marc Bradshaw <marc@marcbradshaw.net>
252 • Bron Gondwana <brong@fastmailteam.com> (ARC)
254
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 • Copyright (C) 2010 by Jason Long
263 • Copyright (C) 2017 by Standcore LLC
265 • Copyright (C) 2020 by FastMail Pty Ltd
267 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.
271perl v5.38.0 2023-07-24 Mail::DKIM::ARC::Verifier(3)