| 1 | package Mail::DMARC::Report::URI; | ||
| 2 | use strict; | ||
| 3 | use warnings; | ||
| 4 | use feature 'signatures'; | ||
| 5 | |||
| 6 | our $VERSION = '2.20260827'; | ||
| 7 | |||
| 8 | use Carp; | ||
| 9 | use URI; | ||
| 10 | |||
| 11 | sub new($class) { | ||
| 12 | return bless {}, $class; | ||
| 13 | } | ||
| 14 | |||
| 15 | sub parse( $self, $str = undef ) { | ||
| 16 | $str or croak "URI string is required!"; | ||
| 17 | |||
| 18 | my @valids = (); | ||
| 19 | foreach my $raw ( split /,/, $str ) { | ||
| 20 | |||
| 21 | # warn "raw: $raw\n"; | ||
| 22 | my ( $u, $size_f ) = split /!/, $raw; | ||
| 23 | my $bytes = $self->get_size_limit($size_f); | ||
| 24 | my $uri = URI->new($u) or do { | ||
| 25 | carp "can't parse URI from $u"; | ||
| 26 | next; | ||
| 27 | }; | ||
| 28 | my $scheme = $uri->scheme or next; | ||
| 29 | if ( $scheme eq 'mailto' && lc substr( $u, 0, 7 ) eq 'mailto:' ) { | ||
| 30 | push @valids, { max_bytes => $bytes, uri => $uri }; | ||
| 31 | next; | ||
| 32 | } | ||
| 33 | if ( $scheme =~ /^http(s)?/x && lc substr( $u, 0, 4 ) eq 'http' ) { | ||
| 34 | push @valids, { max_bytes => $bytes, uri => $uri }; | ||
| 35 | next; | ||
| 36 | } | ||
| 37 | |||
| 38 | # print "invalid URI scheme: $scheme in $u\n"; | ||
| 39 | # 12.1 Discovery - URI schemes found in "rua" tag that are not implemented by | ||
| 40 | # a Mail Receiver MUST be ignored. | ||
| 41 | } | ||
| 42 | return \@valids; | ||
| 43 | } | ||
| 44 | |||
| 45 | sub get_size_limit( $self, $size = undef ) { | ||
| 46 | return 0 if !defined $size; # no limit | ||
| 47 | return $size if $size =~ /^\d+$/; # no units, raw byte count | ||
| 48 | |||
| 49 | # 6.3 Formal Definition | ||
| 50 | # units are considered to be powers of two; a kilobyte is 2^10, a megabyte is 2^20, | ||
| 51 | my $unit = lc chop $size; | ||
| 52 | return $size * ( 2**10 ) if 'k' eq $unit; | ||
| 53 | return $size * ( 2**20 ) if 'm' eq $unit; | ||
| 54 | return $size * ( 2**30 ) if 'g' eq $unit; | ||
| 55 | return $size * ( 2**40 ) if 't' eq $unit; | ||
| 56 | croak "unrecognized unit ($unit) in size ($size)"; | ||
| 57 | } | ||
| 58 | |||
| 59 | 1; | ||
| 60 | |||
| 61 | __END__ | ||
| 62 | |||
| 63 | =pod | ||
| 64 | |||
| 65 | =head1 NAME | ||
| 66 | |||
| 67 | Mail::DMARC::Report::URI - a DMARC report URI | ||
| 68 | |||
| 69 | =head1 VERSION | ||
| 70 | |||
| 71 | version 2.20260827 | ||
| 72 | |||
| 73 | =head1 SYNOPSIS | ||
| 74 | |||
| 75 | use Mail::DMARC::URI; | ||
| 76 | my $duri = Mail::DMARC::URI->new; | ||
| 77 | my $uri_ref = $duri->parse('mailto:rua@example.com,mailto:rua@external.otherdomain.com'); | ||
| 78 | foreach my $u ( @$uri_ref ) { | ||
| 79 | my $method = $u->{uri}; | ||
| 80 | my $max = $u->{max_bytes}; | ||
| 81 | ... do some URI stuff ... | ||
| 82 | }; | ||
| 83 | |||
| 84 | =head1 DESCRIPTION | ||
| 85 | |||
| 86 | defines a generic syntax for identifying a resource. The DMARC | ||
| 87 | mechanism uses this as the format by which a Domain Owner specifies | ||
| 88 | the destination for the two report types that are supported. | ||
| 89 | |||
| 90 | The place such URIs are specified (see Section 6.2) allows a list of | ||
| 91 | these to be provided. A report is to be sent to each listed URI. | ||
| 92 | Mail Receivers MAY impose a limit on the number of URIs that receive | ||
| 93 | reports, but MUST support at least two. The list of URIs is | ||
| 94 | separated by commas (ASCII 0x2C). | ||
| 95 | |||
| 96 | Each URI can have associated with it a maximum report size that may | ||
| 97 | be sent to it. This is accomplished by appending an exclamation | ||
| 98 | point (ASCII 0x21), followed by a maximum size indication, before a | ||
| 99 | separating comma or terminating semi-colon. | ||
| 100 | |||
| 101 | Thus, a DMARC URI is a URI within which any commas or exclamation | ||
| 102 | points are percent-encoded per [URI], followed by an OPTIONAL | ||
| 103 | exclamation point and a maximum size specification, and, if there are | ||
| 104 | additional reporting URIs in the list, a comma and the next URI. | ||
| 105 | |||
| 106 | For example, the URI "mailto:reports@example.com!50m" would request a | ||
| 107 | report be sent via email to "reports@example.com" so long as the | ||
| 108 | report payload does not exceed 50 megabytes. | ||
| 109 | |||
| 110 | A formal definition is provided in Section 6.3. | ||
| 111 | |||
| 112 | =head1 ABNF | ||
| 113 | |||
| 114 | dmarc-uri = URI [ "!" 1*DIGIT [ "k" / "m" / "g" / "t" ] ] | ||
| 115 | ; "URI" is imported from [URI]; commas (ASCII 0x2c) | ||
| 116 | ; and exclamation points (ASCII 0x21) MUST be encoded | ||
| 117 | |||
| 118 | URI is imported from RFC 3986: https://www.ietf.org/rfc/rfc3986.txt | ||
| 119 | |||
| 120 | Only mailto, http, and https URIs are currently supported, examples: | ||
| 121 | |||
| 122 | https://www.ietf.org/rfc/rfc3986.txt | ||
| 123 | mailto:John.Doe@example.com | ||
| 124 | |||
| 125 | With an optional size limit (see SIZE LIMIT). | ||
| 126 | |||
| 127 | =head1 SIZE LIMIT | ||
| 128 | |||
| 129 | A size limitation in a dmarc-uri, if provided, is interpreted as a | ||
| 130 | count of units followed by an OPTIONAL unit size ("k" for kilobytes, | ||
| 131 | "m" for megabytes, "g" for gigabytes, "t" for terabytes). Without a | ||
| 132 | unit, the number is presumed to be a basic byte count. Note that the | ||
| 133 | units are considered to be powers of two; a kilobyte is 2^10, a | ||
| 134 | megabyte is 2^20, etc. | ||
| 135 | |||
| 136 | =head1 AUTHORS | ||
| 137 | |||
| 138 | =over 4 | ||
| 139 | |||
| 140 | =item * | ||
| 141 | |||
| 142 | Matt Simerson <msimerson@cpan.org> | ||
| 143 | |||
| 144 | =item * | ||
| 145 | |||
| 146 | Davide Migliavacca <shari@cpan.org> | ||
| 147 | |||
| 148 | =item * | ||
| 149 | |||
| 150 | Marc Bradshaw <marc@marcbradshaw.net> | ||
| 151 | |||
| 152 | =back | ||
| 153 | |||
| 154 | =head1 COPYRIGHT AND LICENSE | ||
| 155 | |||
| 156 | This software is copyright (c) 2026 by Matt Simerson. | ||
| 157 | |||
| 158 | This is free software; you can redistribute it and/or modify it under | ||
| 159 | the same terms as the Perl 5 programming language system itself. | ||
| 160 | |||
| 161 | =cut |