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 use Mail::DKIM::ARC::Verifier;
10 # create a verifier object
12 my $arc = Mail::DKIM::ARC::Verifier->new();
13 # read an email from a file handle
15 $arc->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 $arc->PRINT("$_\015\012");
26 }
27 $arc->CLOSE;
28 # what is the result of the verify?
30 my $result = $arc->result;
31 # print the results for all the message-signatures and seals on the message
33 foreach my $signature ($arc->signatures)
34 {
35 print $signature->prefix() . ' v=' . $signature->instance .
36 ' ' . $signature->result_detail . "\n";
37 }
38 # example output. Note that to pass, only the MOST RECENT ARC-Message-Signature
40 # must match, because other steps may have modified the signature. What matters
41 # is that all ARC-Seals pass, and the most recent ARC-Message-Signature passes.
42
44 The verifier object allows an email message to be scanned for ARC seals
45 and their associated signatures to be verified. The verifier tracks the
46 state of the message as it is read into memory. When the message has
47 been completely read, the signatures are verified and the results of
48 the verification can be accessed.
49 To use the verifier, first create the verifier object. Then start
51 "feeding" it the email message to be verified. When all the _headers_
52 have been read, the verifier:
53 1. checks whether any ARC signatures were found
55 2. queries for the public keys needed to verify the signatures
56 3. sets up the appropriate algorithms and canonicalization objects
57 4. canonicalizes the headers and computes the header hash
58 Then, when the _body_ of the message has been completely fed into the
60 verifier, the body hash is computed and the signatures are verified.
61 The results of the verification can be checked with "result()" or
63 "signatures()".
64 The final result is calculated by the algorithm layed out in
66 https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-06 - if ALL
67 ARC-Seal headers pass and the highest index (i=) ARC-Message-Signature
68 passes, then the seal is intact.
69
71 new()
72 Constructs an object-oriented verifier.
73 my $arc = Mail::DKIM::ARC::Verifier->new();
75 my $arc = Mail::DKIM::ARC::Verifier->new(%options);
77 The only options supported at this time are:
79 AS_Canonicalization
81 if specified, the canonicalized message for the ARC-Seal is written
82 to the referenced string or file handle.
83 AMA_Canonicalization
85 if specified, the canonicalized message for the ARC-Message-
86 Signature is written to the referenced string or file handle.
87 Strict
89 If true, rejects sha1 hashes and signing keys shorter than 1024
90 bits.
91
93 PRINT()
94 Feeds part of the message to the verifier.
95 $arc->PRINT("a line of the message\015\012");
97 $arc->PRINT('more of');
98 $arc->PRINT(" the message\015\012bye\015\012");
99 Feeds content of the message being verified into the verifier. The API
101 is designed this way so that the entire message does NOT need to be
102 read into memory at once.
103 Please note that although the PRINT() method expects you to use SMTP-
105 style line termination characters, you should NOT use the SMTP-style
106 dot-stuffing technique described in RFC 2821 section 4.5.2. Nor should
107 you use a <CR><LF>.<CR><LF> sequence to terminate the message.
108 CLOSE()
110 Call this when finished feeding in the message.
111 $arc->CLOSE;
113 This method finishes the canonicalization process, computes a hash, and
115 verifies the signature.
116 load()
118 Load the entire message from a file handle.
119 $arc->load($file_handle);
121 Reads a complete message from the designated file handle, feeding it
123 into the verifier. The message must use <CRLF> line terminators (same
124 as the SMTP protocol).
125 message_originator()
127 Access the "From" header.
128 my $address = $arc->message_originator;
130 Returns the "originator address" found in the message, as a
132 Mail::Address object. This is typically the (first) name and email
133 address found in the From: header. If there is no From: header, then an
134 empty Mail::Address object is returned.
135 To get just the email address part, do:
137 my $email = $arc->message_originator->address;
139 See also "message_sender()".
141 message_sender()
143 Access the "From" or "Sender" header.
144 my $address = $arc->message_sender;
146 Returns the "sender" found in the message, as a Mail::Address object.
148 This is typically the (first) name and email address found in the
149 Sender: header. If there is no Sender: header, it is the first name and
150 email address in the From: header. If neither header is present, then
151 an empty Mail::Address object is returned.
152 To get just the email address part, do:
154 my $email = $arc->message_sender->address;
156 The "sender" is the mailbox of the agent responsible for the actual
158 transmission of the message. For example, if a secretary were to send a
159 message for another person, the "sender" would be the secretary and the
160 "originator" would be the actual author.
161 result()
163 Access the result of the verification.
164 my $result = $arc->result;
166 Gives the result of the verification. The following values are
168 possible:
169 pass
171 Returned if a valid ARC chain was found, with all the ARC-Seals
172 passing, and the most recent (highest index) ARC-Message-Signature
173 passing.
174 fail
176 Returned if any ARC-Seal failed, or if the ARC-Message-Signature
177 failed. Will also be a fail if there is a DNS temporary failure,
178 which is a known flaw in this version of the ARC::Verifier. Future
179 versions may reject this message outright (4xx) and ask the sender
180 to attempt delivery later to avoid creating a broken chain. There
181 is no temperror for ARC, as it doesn't make sense to sign a chain
182 with temperror in it or every spammer would just use one of those.
183 invalid
185 Returned if a ARC-Seal could not be checked because of a problem in
186 the signature itself or the public key record. I.e. the signature
187 could not be processed.
188 none
190 Returned if no ARC-* headers were found.
191 result_detail()
193 Access the result, plus details if available.
194 my $detail = $dkim->result_detail;
196 The detail is constructed by taking the result (e.g. "pass", "fail",
198 "invalid" or "none") and appending any details provided by the
199 verification process for the topmost ARC-Seal in parenthesis.
200 The following are possible results from the result_detail() method:
202 pass
204 fail (bad RSA signature)
205 fail (OpenSSL error: ...)
206 fail (message has been altered)
207 fail (body has been altered)
208 invalid (bad instance)
209 invalid (invalid domain in d tag)
210 invalid (missing q tag)
211 invalid (missing d tag)
212 invalid (missing s tag)
213 invalid (unsupported version 0.1)
214 invalid (unsupported algorithm ...)
215 invalid (unsupported canonicalization ...)
216 invalid (unsupported query protocol ...)
217 invalid (signature is expired)
218 invalid (public key: not available)
219 invalid (public key: unknown query type ...)
220 invalid (public key: syntax error)
221 invalid (public key: unsupported version)
222 invalid (public key: unsupported key type)
223 invalid (public key: missing p= tag)
224 invalid (public key: invalid data)
225 invalid (public key: does not support email)
226 invalid (public key: does not support hash algorithm 'sha1')
227 invalid (public key: does not support signing subdomains)
228 invalid (public key: revoked)
229 invalid (public key: granularity mismatch)
230 invalid (public key: granularity is empty)
231 invalid (public key: OpenSSL error: ...)
232 none
233 signatures()
235 Access all of this message's signatures.
236 my @all_signatures = $arc->signatures;
238 Use $signature->result or $signature->result_detail to access the
240 verification results of each signature.
241 Use $signature->instance and $signature->prefix to find the instance
243 and header-name for each signature.
244
246 Bron Gondwana, <brong@fastmailteam.com>
247
249 Copyright (C) 2017 FastMail Pty Ltd.
250 This library is free software; you can redistribute it and/or modify it
252 under the same terms as Perl itself, either Perl version 5.8.6 or, at
253 your option, any later version of Perl 5 you may have available.
254perl v5.26.3 2018-10-13 Mail::DKIM::ARC::Verifier(3)