.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Mail::DMARC::Report::Aggregate 3pm" .TH Mail::DMARC::Report::Aggregate 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Mail::DMARC::Report::Aggregate \- aggregate report object .SH "VERSION" .IX Header "VERSION" version 1.20230215 .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class is used as the canonization of an aggregate report. .PP When reports are received, the \s-1XML\s0 is parsed into an Aggregate object, which then gets passed to the Report::Store and saved. When sending \s-1DMARC\s0 reports, data is extracted from the Store as an Aggregate object, exported as \s-1XML,\s0 and sent. .SH "2013 Draft Description" .IX Header "2013 Draft Description" \&\s-1AGGREGATE REPORTS\s0 .PP The report \s-1SHOULD\s0 include the following data: .PP .Vb 3 \& o Enough information for the report consumer to re\-calculate DMARC \& disposition based on the published policy, message disposition, and \& SPF, DKIM, and identifier alignment results. {R12} \& \& o Data for each sender subdomain separately from mail from the \& sender\*(Aqs organizational domain, even if no subdomain policy is \& applied. {R13} \& \& o Sending and receiving domains {R17} \& \& o The policy requested by the Domain Owner and the policy actually \& applied (if different) {R18} \& \& o The number of successful authentications {R19} \& \& o The counts of messages based on all messages received even if \& their delivery is ultimately blocked by other filtering agents {R20} .Ve .PP Aggregate reports are most useful when they all cover a common time period. By contrast, correlation of these reports from multiple generators when they cover incongruous time periods is difficult or impossible. Report generators \s-1SHOULD,\s0 wherever possible, adhere to hour boundaries for the reporting period they are using. For example, starting a per-day report at 00:00; starting per-hour reports at 00:00, 01:00, 02:00; et cetera. Report Generators using a 24\-hour report period are strongly encouraged to begin that period at 00:00 \s-1UTC,\s0 regardless of local timezone or time of report production, in order to facilitate correlation. .SH "Report Structure" .IX Header "Report Structure" This is a translation of the \s-1XML\s0 report format in the 2013 Draft, converted to perl data structures. .PP .Vb 10 \& feedback => { \& version => 1.0, # decimal \& report_metadata => { # info about DMARC reporter \& report_id => string \& org_name => \*(AqArt Farm\*(Aq, \& email => \*(Aqno\-reply@theartfarm.com\*(Aq, \& extra_contact_info => string # min 0 \& date_range => { \& begin => epoch time, \& end => epoch time, \& }, \& error => string, # min 0, max unbounded \& }, \& policy_published => { \& domain => string \& adkim => r, s \& aspf => r, s \& p => none, quarantine, reject \& sp => none, quarantine, reject \& pct => integer \& fo => string \& }, \& record => [ \& { row => { \& source_ip => # IPAddress \& count => # integer \& policy_evaluated => { # min=1 \& disposition => # none, quarantine, reject \& dkim => # pass, fail \& spf => # pass, fail \& reason => [ # min 0, max unbounded \& { type => # forwarded sampled_out, trusted_forwarder, mailing_list, local_policy, other \& comment => # string, min 0 \& }, \& ], \& } \& }, \& identifiers => { \& envelope_to min=0 \& envelope_from min=1 \& header_from min=1 \& }, \& auth_results => { \& spf => [ # min 1, max unbounded \& { domain => # min 1 \& scope => # min 1, helo, mfrom \& result => # min 1, none neutral pass fail softfail temperror permerror \& } \& ] # ( unknown \-> temperror, error \-> permerror ) \& dkim => [ # min 0, max unbounded \& { domain => , # min 1, the d= parameter in the signature \& selector => , # min 0, string \& result => , # none pass fail policy neutral temperror permerror \& human_result => # min 0, string \& }, \& ], \& }, \& ] \& }, \& }; .Ve .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Matt Simerson .IP "\(bu" 4 Davide Migliavacca .IP "\(bu" 4 Marc Bradshaw .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2023 by Matt Simerson. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.