1=encoding utf8
2
3=head1 NAME
4
5Mail::Message::Field::AuthResults - message header field authentication result
6
7=head1 INHERITANCE
8
9 Mail::Message::Field::AuthResults
10   is a Mail::Message::Field::Structured
11   is a Mail::Message::Field::Full
12   is a Mail::Message::Field
13   is a Mail::Reporter
14
15=head1 SYNOPSIS
16
17 my $f = Mail::Message::Field->new('Authentication-Results' => '...');
18
19 my $g = Mail::Message::Field->new('Authentication-Results');
20 $g->addResult(method => 'dkim', result => 'fail');
21
22=head1 DESCRIPTION
23
24Mail Transfer Agents may check the authenticity of an incoming message.
25They add 'Authentication-Results' headers, maybe more than one.  This
26implementation is based on RFC7601.
27
28Extends L<"DESCRIPTION" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DESCRIPTION">.
29
30=head1 OVERLOADED
31
32Extends L<"OVERLOADED" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"OVERLOADED">.
33
34=over 4
35
36=item overload: B<"">
37
38Inherited, see L<Mail::Message::Field/"OVERLOADED">
39
40=item overload: B<0+>
41
42Inherited, see L<Mail::Message::Field/"OVERLOADED">
43
44=item overload: B<<=>>
45
46Inherited, see L<Mail::Message::Field/"OVERLOADED">
47
48=item overload: B<bool>
49
50Inherited, see L<Mail::Message::Field/"OVERLOADED">
51
52=item overload: B<cmp>
53
54Inherited, see L<Mail::Message::Field/"OVERLOADED">
55
56=item overload: B<stringification>
57
58Inherited, see L<Mail::Message::Field::Full/"OVERLOADED">
59
60=back
61
62=head1 METHODS
63
64Extends L<"METHODS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"METHODS">.
65
66=head2 Constructors
67
68Extends L<"Constructors" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Constructors">.
69
70=over 4
71
72=item $obj-E<gt>B<clone>()
73
74Inherited, see L<Mail::Message::Field/"Constructors">
75
76=item Mail::Message::Field::AuthResults-E<gt>B<from>($field, %options)
77
78Inherited, see L<Mail::Message::Field::Full/"Constructors">
79
80=item Mail::Message::Field::AuthResults-E<gt>B<new>($data)
81
82 -Option    --Defined in                      --Default
83  attributes  Mail::Message::Field::Structured  <ignored>
84  charset     Mail::Message::Field::Full        undef
85  datum       Mail::Message::Field::Structured  undef
86  encoding    Mail::Message::Field::Full        'q'
87  force       Mail::Message::Field::Full        false
88  language    Mail::Message::Field::Full        undef
89  log         Mail::Reporter                    'WARNINGS'
90  results                                       []
91  server                                        <required>
92  trace       Mail::Reporter                    'WARNINGS'
93  version                                       undef
94
95=over 2
96
97=item attributes => ATTRS
98
99=item charset => STRING
100
101=item datum => STRING
102
103=item encoding => 'q'|'Q'|'b'|'B'
104
105=item force => BOOLEAN
106
107=item language => STRING
108
109=item log => LEVEL
110
111=item results => ARRAY
112
113Each authentication method is represented by a HASH, which contains
114the 'method' and 'result' keys.  Sometimes, there is a 'comment'.
115Properties of form 'ptype.pname' will be there as well.
116
117=item server => DOMAIN
118
119Where the authentication tool ran.  This should be your local service,
120otherwise you may accept spoofed headers!
121
122=item trace => LEVEL
123
124=item version => INTEGER
125
126=back
127
128=back
129
130=head2 The field
131
132Extends L<"The field" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"The field">.
133
134=over 4
135
136=item $obj-E<gt>B<isStructured>()
137
138=item Mail::Message::Field::AuthResults-E<gt>B<isStructured>()
139
140Inherited, see L<Mail::Message::Field/"The field">
141
142=item $obj-E<gt>B<length>()
143
144Inherited, see L<Mail::Message::Field/"The field">
145
146=item $obj-E<gt>B<nrLines>()
147
148Inherited, see L<Mail::Message::Field/"The field">
149
150=item $obj-E<gt>B<print>( [$fh] )
151
152Inherited, see L<Mail::Message::Field/"The field">
153
154=item $obj-E<gt>B<size>()
155
156Inherited, see L<Mail::Message::Field/"The field">
157
158=item $obj-E<gt>B<string>( [$wrap] )
159
160Inherited, see L<Mail::Message::Field/"The field">
161
162=item $obj-E<gt>B<toDisclose>()
163
164Inherited, see L<Mail::Message::Field/"The field">
165
166=back
167
168=head2 Access to the name
169
170Extends L<"Access to the name" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the name">.
171
172=over 4
173
174=item $obj-E<gt>B<Name>()
175
176Inherited, see L<Mail::Message::Field/"Access to the name">
177
178=item $obj-E<gt>B<name>()
179
180Inherited, see L<Mail::Message::Field/"Access to the name">
181
182=item $obj-E<gt>B<wellformedName>( [STRING] )
183
184Inherited, see L<Mail::Message::Field/"Access to the name">
185
186=back
187
188=head2 Access to the body
189
190Extends L<"Access to the body" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the body">.
191
192=over 4
193
194=item $obj-E<gt>B<body>()
195
196Inherited, see L<Mail::Message::Field/"Access to the body">
197
198=item $obj-E<gt>B<decodedBody>(%options)
199
200Inherited, see L<Mail::Message::Field::Full/"Access to the body">
201
202=item $obj-E<gt>B<folded>()
203
204Inherited, see L<Mail::Message::Field/"Access to the body">
205
206=item $obj-E<gt>B<foldedBody>( [$body] )
207
208Inherited, see L<Mail::Message::Field/"Access to the body">
209
210=item $obj-E<gt>B<stripCFWS>( [STRING] )
211
212=item Mail::Message::Field::AuthResults-E<gt>B<stripCFWS>( [STRING] )
213
214Inherited, see L<Mail::Message::Field/"Access to the body">
215
216=item $obj-E<gt>B<unfoldedBody>( [$body, [$wrap]] )
217
218Inherited, see L<Mail::Message::Field/"Access to the body">
219
220=back
221
222=head2 Access to the content
223
224Extends L<"Access to the content" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the content">.
225
226=over 4
227
228=item $obj-E<gt>B<addAttribute>(...)
229
230Attributes are not supported here.
231
232=item $obj-E<gt>B<addResult>(HASH|PAIRS)
233
234Add new results to this header.  Invalid results are ignored.
235
236=item $obj-E<gt>B<addresses>()
237
238Inherited, see L<Mail::Message::Field/"Access to the content">
239
240=item $obj-E<gt>B<attrPairs>()
241
242Inherited, see L<Mail::Message::Field::Structured/"Access to the content">
243
244=item $obj-E<gt>B<attribute>( $object|<STRING, %options>|<$name,$value,%options> )
245
246Inherited, see L<Mail::Message::Field::Structured/"Access to the content">
247
248=item $obj-E<gt>B<attributes>()
249
250Inherited, see L<Mail::Message::Field::Structured/"Access to the content">
251
252=item $obj-E<gt>B<beautify>()
253
254Inherited, see L<Mail::Message::Field::Full/"Access to the content">
255
256=item $obj-E<gt>B<comment>( [STRING] )
257
258Inherited, see L<Mail::Message::Field/"Access to the content">
259
260=item $obj-E<gt>B<createComment>(STRING, %options)
261
262=item Mail::Message::Field::AuthResults-E<gt>B<createComment>(STRING, %options)
263
264Inherited, see L<Mail::Message::Field::Full/"Access to the content">
265
266=item $obj-E<gt>B<createPhrase>(STRING, %options)
267
268=item Mail::Message::Field::AuthResults-E<gt>B<createPhrase>(STRING, %options)
269
270Inherited, see L<Mail::Message::Field::Full/"Access to the content">
271
272=item $obj-E<gt>B<results>()
273
274Returns a LIST of result HASHes.  Each HASH at least contains keys 'method',
275'method_version', and 'result'.
276
277=item $obj-E<gt>B<server>()
278
279The hostname which ran this authentication tool.
280
281=item $obj-E<gt>B<study>()
282
283Inherited, see L<Mail::Message::Field/"Access to the content">
284
285=item $obj-E<gt>B<toDate>( [$time] )
286
287=item Mail::Message::Field::AuthResults-E<gt>B<toDate>( [$time] )
288
289Inherited, see L<Mail::Message::Field/"Access to the content">
290
291=item $obj-E<gt>B<toInt>()
292
293Inherited, see L<Mail::Message::Field/"Access to the content">
294
295=item $obj-E<gt>B<version>()
296
297The version of the 'Authentication-Results' header, which may be different
298from '1' (default) for successors of RFC7601.
299
300=back
301
302=head2 Other methods
303
304Extends L<"Other methods" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Other methods">.
305
306=over 4
307
308=item $obj-E<gt>B<dateToTimestamp>(STRING)
309
310=item Mail::Message::Field::AuthResults-E<gt>B<dateToTimestamp>(STRING)
311
312Inherited, see L<Mail::Message::Field/"Other methods">
313
314=back
315
316=head2 Internals
317
318Extends L<"Internals" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Internals">.
319
320=over 4
321
322=item $obj-E<gt>B<consume>( $line | <$name,<$body|$objects>> )
323
324Inherited, see L<Mail::Message::Field/"Internals">
325
326=item $obj-E<gt>B<decode>(STRING, %options)
327
328=item Mail::Message::Field::AuthResults-E<gt>B<decode>(STRING, %options)
329
330Inherited, see L<Mail::Message::Field::Full/"Internals">
331
332=item $obj-E<gt>B<defaultWrapLength>( [$length] )
333
334Inherited, see L<Mail::Message::Field/"Internals">
335
336=item $obj-E<gt>B<encode>(STRING, %options)
337
338Inherited, see L<Mail::Message::Field::Full/"Internals">
339
340=item $obj-E<gt>B<fold>( $name, $body, [$maxchars] )
341
342=item Mail::Message::Field::AuthResults-E<gt>B<fold>( $name, $body, [$maxchars] )
343
344Inherited, see L<Mail::Message::Field/"Internals">
345
346=item $obj-E<gt>B<setWrapLength>( [$length] )
347
348Inherited, see L<Mail::Message::Field/"Internals">
349
350=item $obj-E<gt>B<stringifyData>(STRING|ARRAY|$objects)
351
352Inherited, see L<Mail::Message::Field/"Internals">
353
354=item $obj-E<gt>B<unfold>(STRING)
355
356Inherited, see L<Mail::Message::Field/"Internals">
357
358=back
359
360=head2 Parsing
361
362Extends L<"Parsing" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Parsing">.
363
364=over 4
365
366=item $obj-E<gt>B<consumeComment>(STRING)
367
368=item Mail::Message::Field::AuthResults-E<gt>B<consumeComment>(STRING)
369
370Inherited, see L<Mail::Message::Field::Full/"Parsing">
371
372=item $obj-E<gt>B<consumeDotAtom>(STRING)
373
374Inherited, see L<Mail::Message::Field::Full/"Parsing">
375
376=item $obj-E<gt>B<consumePhrase>(STRING)
377
378=item Mail::Message::Field::AuthResults-E<gt>B<consumePhrase>(STRING)
379
380Inherited, see L<Mail::Message::Field::Full/"Parsing">
381
382=item $obj-E<gt>B<datum>( [$value] )
383
384Inherited, see L<Mail::Message::Field::Structured/"Parsing">
385
386=item $obj-E<gt>B<parse>(STRING)
387
388Inherited, see L<Mail::Message::Field::Full/"Parsing">
389
390=item $obj-E<gt>B<produceBody>()
391
392Inherited, see L<Mail::Message::Field::Full/"Parsing">
393
394=back
395
396=head2 Error handling
397
398Extends L<"Error handling" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Error handling">.
399
400=over 4
401
402=item $obj-E<gt>B<AUTOLOAD>()
403
404Inherited, see L<Mail::Reporter/"Error handling">
405
406=item $obj-E<gt>B<addReport>($object)
407
408Inherited, see L<Mail::Reporter/"Error handling">
409
410=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
411
412=item Mail::Message::Field::AuthResults-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
413
414Inherited, see L<Mail::Reporter/"Error handling">
415
416=item $obj-E<gt>B<errors>()
417
418Inherited, see L<Mail::Reporter/"Error handling">
419
420=item $obj-E<gt>B<log>( [$level, [$strings]] )
421
422=item Mail::Message::Field::AuthResults-E<gt>B<log>( [$level, [$strings]] )
423
424Inherited, see L<Mail::Reporter/"Error handling">
425
426=item $obj-E<gt>B<logPriority>($level)
427
428=item Mail::Message::Field::AuthResults-E<gt>B<logPriority>($level)
429
430Inherited, see L<Mail::Reporter/"Error handling">
431
432=item $obj-E<gt>B<logSettings>()
433
434Inherited, see L<Mail::Reporter/"Error handling">
435
436=item $obj-E<gt>B<notImplemented>()
437
438Inherited, see L<Mail::Reporter/"Error handling">
439
440=item $obj-E<gt>B<report>( [$level] )
441
442Inherited, see L<Mail::Reporter/"Error handling">
443
444=item $obj-E<gt>B<reportAll>( [$level] )
445
446Inherited, see L<Mail::Reporter/"Error handling">
447
448=item $obj-E<gt>B<trace>( [$level] )
449
450Inherited, see L<Mail::Reporter/"Error handling">
451
452=item $obj-E<gt>B<warnings>()
453
454Inherited, see L<Mail::Reporter/"Error handling">
455
456=back
457
458=head2 Cleanup
459
460Extends L<"Cleanup" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Cleanup">.
461
462=over 4
463
464=item $obj-E<gt>B<DESTROY>()
465
466Inherited, see L<Mail::Reporter/"Cleanup">
467
468=back
469
470=head1 DETAILS
471
472Extends L<"DETAILS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DETAILS">.
473
474=head1 DIAGNOSTICS
475
476=over 4
477
478=item Warning: Field content is not numerical: $content
479
480The numeric value of a field is requested (for instance the C<Lines> or
481C<Content-Length> fields should be numerical), however the data contains
482weird characters.
483
484=item Warning: Illegal character in charset '$charset'
485
486The field is created with an utf8 string which only contains data from the
487specified character set.  However, that character set can never be a valid
488name because it contains characters which are not permitted.
489
490=item Warning: Illegal character in field name $name
491
492A new field is being created which does contain characters not permitted
493by the RFCs.  Using this field in messages may break other e-mail clients
494or transfer agents, and therefore mutulate or extinguish your message.
495
496=item Warning: Illegal character in language '$lang'
497
498The field is created with data which is specified to be in a certain language,
499however, the name of the language cannot be valid: it contains characters
500which are not permitted by the RFCs.
501
502=item Warning: Illegal encoding '$encoding', used 'q'
503
504The RFCs only permit base64 (C<b > or C<B >) or quoted-printable
505(C<q> or C<Q>) encoding.  Other than these four options are illegal.
506
507=item Error: No attributes for Authentication-Results
508
509Is is not possible to add attributes to this field.
510
511=item Error: Package $package does not implement $method.
512
513Fatal error: the specific package (or one of its superclasses) does not
514implement this method where it should. This message means that some other
515related classes do implement this method however the class at hand does
516not.  Probably you should investigate this and probably inform the author
517of the package.
518
519=back
520
521=head1 SEE ALSO
522
523This module is part of Mail-Message distribution version 3.011,
524built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/>
525
526=head1 LICENSE
527
528Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
529
530This program is free software; you can redistribute it and/or modify it
531under the same terms as Perl itself.
532See F<http://dev.perl.org/licenses/>
533
534