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

SYNOPSIS

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

DESCRIPTION

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
50       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
54        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
59       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
62       The results of the verification can be checked with "result()" or
63       "signatures()".
64
65       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

CONSTRUCTOR

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

METHODS

93   PRINT()
94       Feeds part of the message to the verifier.
95
96         $arc->PRINT("a line of the message\015\012");
97         $arc->PRINT('more of');
98         $arc->PRINT(" the message\015\012bye\015\012");
99
100       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
104       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
109   CLOSE()
110       Call this when finished feeding in the message.
111
112         $arc->CLOSE;
113
114       This method finishes the canonicalization process, computes a hash, and
115       verifies the signature.
116
117   load()
118       Load the entire message from a file handle.
119
120         $arc->load($file_handle);
121
122       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
126   message_originator()
127       Access the "From" header.
128
129         my $address = $arc->message_originator;
130
131       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
136       To get just the email address part, do:
137
138         my $email = $arc->message_originator->address;
139
140       See also "message_sender()".
141
142   message_sender()
143       Access the "From" or "Sender" header.
144
145         my $address = $arc->message_sender;
146
147       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
153       To get just the email address part, do:
154
155         my $email = $arc->message_sender->address;
156
157       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
162   result()
163       Access the result of the verification.
164
165         my $result = $arc->result;
166
167       Gives the result of the verification. The following values are
168       possible:
169
170       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
175       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
184       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
189       none
190           Returned if no ARC-* headers were found.
191
192   result_detail()
193       Access the result, plus details if available.
194
195         my $detail = $dkim->result_detail;
196
197       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
201       The following are possible results from the result_detail() method:
202
203         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
234   signatures()
235       Access all of this message's signatures.
236
237         my @all_signatures = $arc->signatures;
238
239       Use $signature->result or $signature->result_detail to access the
240       verification results of each signature.
241
242       Use $signature->instance and $signature->prefix to find the instance
243       and header-name for each signature.
244

AUTHOR

246       Bron Gondwana, <brong@fastmailteam.com>
247
249       Copyright (C) 2017 FastMail Pty Ltd.
250
251       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.
254
255
256
257perl v5.30.1                      2020-01-30      Mail::DKIM::ARC::Verifier(3)
Impressum