lib/Mail/DKIM2/Gate.pm

filter: Statementstmt 95.5% 85 / 89 Branchbran 92.3% 48 / 52 Conditioncond 90.4% 38 / 42 MC/DCmcdc 83.3% 20 / 24 Subroutinesub 100% 13 / 13 Podpod 100% 1 / 1 totaltotal 92.7% 205 / 221 CC 42 SCAR 32.2
CC
42
Cov
93%
check
36.1
_is_handle
6.2
_deprecated_allow_null
2.0
CRAP 25.0
« lib/Mail/DKIM2/RecipeJSON.pm ↑ Summary lib/Mail/DKIM2/Key.pm »
1 package Mail::DKIM2::Gate;
2 101 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 101 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 0 our $VERSION = '0.33';
6  
7 101 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
8 101 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 101 ▶use Mail::DKIM2::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
10 101 ▶use Mail::DKIM2::HeaderParser;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 101 ▶use Mail::DKIM2::Chain;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 101 ▶use Mail::DKIM2::Verifier;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 =head1 NAME
15  
16 Mail::DKIM2::Gate - decide whether a front end may sign a message
17  
18 =head1 SYNOPSIS
19  
20 my $g = Mail::DKIM2::Gate->check($message,
21 PubkeyCallback => $cb, SkipTimestampCheck => 0,
22 AllowNullBodyRecipe => 0);
23 unless ($g->{ok}) { warn "not signing: $g->{message}" }
24  
25 =head1 DESCRIPTION
26  
27 The gate shared by C<bin/dkim2sign>, C<bin/dkim2-milter> and the
28 authentication_milter handler
29 L<Mail::Milter::Authentication::Handler::DKIM2Sign>. Mail::DKIM2::Signer
30 checks only what it needs to sign -- it refuses a chain it cannot number (a
31 DKIM2-Signature with no usable C<i=>, an C<i=> or C<m=> above
32 C<MAX_CHAIN_LENGTH>, a duplicate) but does not verify the upstream
33 signatures or the Message-Instance chain. A front end that extends a DKIM2
34 chain should first make sure the chain is worth extending, which is what this
35 module decides.
36  
37 =head2 check
38  
39 C<< Mail::DKIM2::Gate->check($message, %opts) >> takes the whole message as a
40 string (CRLF line endings) or a filehandle (or an object with C<getline>),
41 and returns a hashref. A filehandle is read a piece at a time, its body
42 going straight into the Verifier, so the message is never held whole.
43 Options:
44 C<PubkeyCallback>, C<Resolver> and C<SkipTimestampCheck> are passed to the
45 Verifier, C<IgnorePrefixes> to both the Verifier and the Message-Instance
46 chain check (the caller's own header fields, hashed by neither end),
47 C<PolicyCallback> is passed to the Verifier too,
48 C<AllowNullBodyRecipe> is deprecated, does nothing and will be removed (see
49 L</Null body Recipes>),
50 C<SigningDomain> is the C<d=> the caller will sign with: when the top
51 upstream signature carries C<nd=> the gate passes only if it equals that
52 domain (case-insensitive) and refuses otherwise ("top signature nd=X names
53 another domain"); without it a top C<nd=> is refused as before.
54 C<VerifyResult> supplies an already-computed verifier result so the upstream
55 signatures are not verified again; the Message-Instance chain still is.
56  
57 The upstream DKIM2-Signatures are verified with a Verifier that allows an
58 unsigned Message-Instance above the top signature (the one the caller is about
59 to sign), and the Message-Instance chain must match the content and undo
60 cleanly down to m=1, including the header history below a null body Recipe.
61 Every From the signed instances have had must be Authentic (-09 section
62 11); a From changed in an instance no upstream signature covers is not
63 checked here but by L<Mail::DKIM2::Signer>, against the C<d=> it signs with.
64  
65 The result has C<ok> (true to sign), C<verify_result> (C<none> without a
66 DKIM2-Signature), C<has_chain>, C<top_null> (the top Message-Instance has a
67 null body Recipe), C<covered_m> (the highest C<m=> of any DKIM2-Signature
68 with a valid, positive-integer C<i=>, or 0: those instances, 1 to
69 C<covered_m>, are signed upstream; a signature without a valid C<i=> never
70 counts, and the Verifier reports it as a C<permerror>), C<top_signed> (the
71 top Message-Instance is among them), C<unsigned_null> (the C<m=> of the
72 highest Message-Instance above C<covered_m> with a null body Recipe -- the
73 top or one under it -- or 0) and, when refusing, C<reason>
74 (C<upstream-chain> or C<broken-mi-chain>; C<null-body-recipe> is no longer
75 given since 0.29) and a human-readable C<message>. C<top_signed>, C<covered_m> and C<unsigned_null>
76 are new in 0.16; C<top_null> is as in 0.15.
77  
78 =head2 Null body Recipes
79  
80 A null body Recipe (C<"b": null>) says the previous body cannot be recreated,
81 and a verifier reports a message carrying one as a PERMERROR (-09 sections 13
82 and 14.2: "has a null recipe"). A DKIM2-Signature with C<m=k> covers
83 Message-Instances 1 to I<k>, so every instance above the highest C<m=> of the
84 valid upstream signatures is unsigned, and this hop's own: typically a list
85 manager that rewrote the body beyond what a Recipe can record and added an
86 unsigned instance for the outbound signer.
87  
88 Since 0.29 the gate passes such a null: the message will not verify
89 downstream whatever this hop does, but signing records and vouches for the
90 header changes this hop made. C<AllowNullBodyRecipe>, which used to be
91 needed for that, is deprecated and does nothing.
92  
93 A null that arrived already signed fails the upstream verification, and is
94 refused as C<upstream-chain> like any other broken upstream chain. The header
95 history below this hop's own null must still check out.
96  
97 =cut
98  
99 # True for a filehandle, as HeaderParser::load tells one from a string.
100 184 ▶sub _is_handle {
Subroutine _is_handle: called CC=6 SCAR=18.2
101 184 my ($input) = @_;
102 184 ▶ return 1 if ref $input eq 'GLOB' || ref \$input eq 'GLOB';
Branch: 1 branch
BranchTrueFalseTotal
if ref $input eq "GLOB" or ref \$input eq "GLOB" 24 160 184
Condition66%2/3
ref $input eq "GLOB" or ref \$input eq "GLOB"
l!l&&r!l&&!r
240160
MC/DC50%1/2
ref $input eq "GLOB" or ref \$input eq "GLOB"
ref $input eq "GLOB" ref \$input eq "GLOB"
Truth table66%2/3
A or B
A= ref $input eq "GLOB"B= ref \$input eq "GLOB"
ABresult
1X1
011
000
103 160 ▶ return 0 unless blessed $input;
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($input) 148 12 160
104 12 my $can = eval { $input->can('getline') };
105 12 ▶ die $@ if ref $@;
Branch: 1 branch
BranchTrueFalseTotal
if ref $@ 0 12 12
106 12 ▶ return $can ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$can ? : 12 0 12
107 }
108  
109 # AllowNullBodyRecipe is retired (0.29, -09 contract E2): this hop's own
110 # null is always signed. Still accepted, so an existing caller does not
111 # croak; a true value is warned about once per process.
112 0 my $warned_allow_null;
113 2 ▶sub _deprecated_allow_null {
Subroutine _deprecated_allow_null: called CC=2 SCAR=6.9
114 2 ▶ return if $warned_allow_null++;
Branch: 1 branch
BranchTrueFalseTotal
if $warned_allow_null++ 1 1 2
115 1 Carp::carp('Mail::DKIM2::Gate: AllowNullBodyRecipe is deprecated and does nothing; '
116 . 'an unsigned null body Recipe is always signed (0.29)');
117 }
118  
119 185 ▶sub check {
Subroutine check: called CC=36 SCAR=35.9
Pod documented
120 185 my ($class, $message, %o) = @_;
121 185 Mail::DKIM2::Util::check_options("$class->check", \%o,
122 qw(SigningDomain AllowNullBodyRecipe SkipTimestampCheck IgnorePrefixes
123 PubkeyCallback PolicyCallback Resolver VerifyResult));
124 # Only a true value asks for the retired behaviour: hm's handler passes
125 # AllowNullBodyRecipe => 0 on every call.
126 184 ▶ _deprecated_allow_null() if $o{AllowNullBodyRecipe};
Branch: 1 branch
BranchTrueFalseTotal
if $o{"AllowNullBodyRecipe"} 2 182 184
127  
128 # A filehandle is read a piece at a time: the header fields here, the body
129 # straight into the Verifier below, so the message is never held whole.
130 184 ▶ my $fh = _is_handle($message) ? $message : undef;
Branch: 1 branch
BranchTrueFalseTotal
_is_handle($message) ? : 36 148 184
131 184 ▶ if ($fh) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fh) 36 148 184
132 36 my $head = '';
133 36 ▶ Mail::DKIM2::HeaderParser::_read_handle($fh, sub { $head .= $_[0]; 1 }, 1);
Subroutine __ANON__: called CC=1 SCAR=0.0
134 36 $message = $head;
135 }
136 # The chain as its fields number it (Mail::DKIM2::Chain): which
137 # signatures and instances there are, and how far the signatures reach.
138 184 my $chain = Mail::DKIM2::Chain->from_message($message);
139 184 ▶ my $has_dk2 = $chain->count('DKIM2-Signature') ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$chain->count('DKIM2-Signature') ? : 119 65 184
140 184 my $top_sig = $chain->top_signature;
141 184 ▶ my $top_nd = $top_sig && length($top_sig->next_domain // '') ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$top_sig && length($top_sig->next_domain // '') ? : 9 175 184
Condition100%5/5
$top_sig and length($top_sig->next_domain // "")
!ll&&!rl&&r
651109
$top_sig->next_domain // ""
l!l
9110
MC/DC100%2/2
$top_sig and length($top_sig->next_domain // "")
$top_sig $top_sig->next_domain
Truth table100%3/3
A and B
A= $top_sigB= $top_sig->next_domain
ABresult
0X0
100
111
142  
143 # nd= bridge: a top signature with nd= may be extended only by the domain
144 # it names. A caller-supplied VerifyResult came from a plain verifier that
145 # refuses any top nd=, so recompute it when we know our own d=.
146 184 my $sd = $o{SigningDomain};
147 184 my $verify_result = $o{VerifyResult};
148 184 ▶ $verify_result = undef
Branch: 1 branch
BranchTrueFalseTotal
if defined $sd and length $sd and $has_dk2 and $top_nd 9 175 184
Condition88%8/9
defined $sd and length $sd and $has_dk2 and $top_nd
!ll&&!rl&&r
116599
defined $sd and length $sd and $has_dk2
!ll&&!rl&&r
793768
defined $sd and length $sd
!ll&&!rl&&r
790105
MC/DC75%3/4
defined $sd and length $sd and $has_dk2 and $top_nd
defined $sd length $sd $has_dk2 $top_nd
Truth table80%4/5
A and B and C and D
A= defined $sdB= length $sdC= $has_dk2D= $top_nd
ABCDresult
0XXX0
10XX0
110X0
11100
11111
149 if defined $sd && length $sd && $has_dk2 && $top_nd;
150 # One Verifier, the body streamed through it. It walks the
151 # Message-Instance chain before it looks at a signature, so with no
152 # signature, or with the signatures verified already (VerifyResult), it
153 # is run for the walk alone; with neither signature nor instance there is
154 # nothing to walk. A walk that fails under the signatures is an
155 # upstream-chain refusal below; on its own it is broken-mi-chain.
156 184 my ($chain_ok, $chain_why) = (1, undef);
157 184 ▶ my $instances_only = defined $verify_result || !$has_dk2;
Condition100%3/3
defined $verify_result || !$has_dk2
l!l&&r!l&&!r
335398
MC/DC100%2/2
defined $verify_result || !$has_dk2
defined $verify_result !$has_dk2
Truth table100%3/3
A || not(B)
A= defined $verify_resultB= !$has_dk2
ABresult
1X1
011
000
158 184 ▶ if ($has_dk2 || $chain->count('Message-Instance')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($has_dk2 or $chain->count("Message-Instance")) 164 20 184
Condition100%3/3
$has_dk2 or $chain->count("Message-Instance")
l!l&&r!l&&!r
1194520
MC/DC100%2/2
$has_dk2 or $chain->count("Message-Instance")
$has_dk2 $chain->count("Message-Instance")
Truth table100%3/3
A or B
A= $has_dk2B= $chain->count("Message-Instance")
ABresult
1X1
011
000
159 my $v = Mail::DKIM2::Verifier->new(
160 SkipTimestampCheck => $o{SkipTimestampCheck} ? 1 : 0,
161 InstancesOnly => $instances_only ? 1 : 0,
162 ($o{PubkeyCallback} ? (PubkeyCallback => $o{PubkeyCallback}) : ()),
163 ($o{PolicyCallback} ? (PolicyCallback => $o{PolicyCallback}) : ()),
164 ($o{Resolver} ? (Resolver => $o{Resolver}) : ()),
165 164 ▶ ($o{IgnorePrefixes} ? (IgnorePrefixes => $o{IgnorePrefixes}) : ()));
Branch: 6 branches
BranchTrueFalseTotal
$o{'SkipTimestampCheck'} ? : 51 113 164
$instances_only ? : 66 98 164
$o{'PubkeyCallback'} ? : 164 0 164
$o{'PolicyCallback'} ? : 92 72 164
$o{'Resolver'} ? : 0 164 164
$o{'IgnorePrefixes'} ? : 47 117 164
166 164 $v->allow_unsigned_mi(1);
167 164 ▶ $v->next_domain_ok($sd) if defined $sd && length $sd;
Branch: 1 branch
BranchTrueFalseTotal
if defined $sd and length $sd 96 68 164
Condition66%2/3
defined $sd and length $sd
!ll&&!rl&&r
68096
MC/DC50%1/2
defined $sd and length $sd
defined $sd length $sd
Truth table66%2/3
A and B
A= defined $sdB= length $sd
ABresult
0X0
100
111
168 164 $v->PRINT($message);
169 Mail::DKIM2::HeaderParser::_read_handle($fh,
170 164 ▶ sub { $v->PRINT($_[0]); !$v->stopped }) if $fh;
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 1 branch
BranchTrueFalseTotal
if $fh 30 134 164
171 164 $v->CLOSE();
172 164 ▶ if ($instances_only) {
Branch: 1 branch
BranchTrueFalseTotal
if ($instances_only) { } 66 98 164
173 66 ▶ ($chain_ok, $chain_why) = (0, $v->details)
Branch: 1 branch
BranchTrueFalseTotal
unless $v->result =~ /\A(?:pass|none)\z/ 21 45 66
174 unless $v->result =~ /\A(?:pass|none)\z/;
175 } else {
176 98 $verify_result = $v->result_detail();
177 }
178 }
179 184 ▶ $verify_result //= 'none';
Condition100%2/2
$verify_result //= "none"
l!l
13153
MC/DC100%1/1
$verify_result //= "none"
$verify_result
Truth table100%2/2
A
A= $verify_result
Aresult
11
00
180  
181 184 my $top = $chain->top_instance;
182 46 my %null = map { $_ => 1 }
183 184 ▶ grep { my $mi = $chain->instance($_); $mi && $mi->unrecoverable }
Condition66%2/3
$mi && $mi->unrecoverable
!ll&&!rl&&r
019146
MC/DC50%1/2
$mi && $mi->unrecoverable
$mi $mi->unrecoverable
Truth table66%2/3
A && B
A= $miB= $mi->unrecoverable
ABresult
0X0
100
111
184 $chain->instance_numbers;
185 184 ▶ my $top_null = ($top && $null{$top}) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$top && $null{$top} ? : 42 142 184
Condition100%3/3
$top and $null{$top}
!ll&&!rl&&r
2012242
MC/DC100%2/2
$top and $null{$top}
$top $null{$top}
Truth table100%3/3
A and B
A= $topB= $null{$top}
ABresult
0X0
100
111
186 # How far up the upstream signatures reach: every instance above the
187 # highest m= any of them names is unsigned -- this hop will be the first
188 # to vouch for it. Only a signature the chain could number counts: one it
189 # could not is a PERMERROR to the Verifier (so the upstream-chain check
190 # below refuses anyway), and is never coverage here even if a
191 # caller-supplied VerifyResult said "pass".
192 184 my $covered = $chain->covered_m;
193 184 ▶ my $top_signed = ($top && $top <= $covered) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$top && $top <= $covered ? : 61 123 184
Condition100%3/3
$top and $top <= $covered
!ll&&!rl&&r
2010361
MC/DC100%2/2
$top and $top <= $covered
$top $top <= $covered
Truth table100%3/3
A and B
A= $topB= $top <= $covered
ABresult
0X0
100
111
194 # The highest unsigned instance with a null body Recipe, the top's own or
195 # one under another unsigned instance: a null nobody upstream signed.
196 0 my ($unsigned_null) = sort { $b <=> $a } grep { $_ > $covered } keys %null;
197 184 ▶ $unsigned_null //= 0;
Condition100%2/2
$unsigned_null //= 0
l!l
39145
MC/DC100%1/1
$unsigned_null //= 0
$unsigned_null
Truth table100%2/2
A
A= $unsigned_null
Aresult
11
00
198  
199 184 my %r = (ok => 0, verify_result => $verify_result,
200 has_chain => $has_dk2, top_null => $top_null,
201 top_signed => $top_signed, covered_m => $covered,
202 unsigned_null => $unsigned_null);
203 184 ▶ if ($has_dk2 && $verify_result !~ /^pass/) {
Branch: 2 branches
BranchTrueFalseTotal
if ($has_dk2 and not $verify_result =~ /^pass/) { } 47 137 184
elsif (not $chain_ok) { } 21 116 137
Condition100%3/3
$has_dk2 and not $verify_result =~ /^pass/
!ll&&!rl&&r
657247
MC/DC100%2/2
$has_dk2 and not $verify_result =~ /^pass/
$has_dk2 not $verify_result =~ /^pass/
Truth table100%3/3
A and not(B)
A= $has_dk2B= not $verify_result =~ /^pass/
ABresult
0X0
100
111
204 47 @r{qw(reason message)} = ('upstream-chain',
205 "upstream DKIM2 chain result=$verify_result");
206 } elsif (!$chain_ok) {
207 21 @r{qw(reason message)} = ('broken-mi-chain',
208 "Message-Instance chain does not undo cleanly: $chain_why");
209 } else {
210 116 $r{ok} = 1;
211 }
212 184 return \%r;
213 }
214  
215 0 1;
« lib/Mail/DKIM2/RecipeJSON.pm ↑ Summary lib/Mail/DKIM2/Key.pm »