1Mail::SPF::Iterator(3)User Contributed Perl DocumentationMail::SPF::Iterator(3)
2
6 Mail::SPF::Iterator - iterative SPF lookup
7
9 use Net::DNS;
10 use Mail::SPF::Iterator;
11 use Mail::SPF::Iterator Debug =>1; # enable debugging
12 my $spf = Mail::SPF::Iterator->new(
13 $ip, # IP4|IP6 of client
14 $mailfrom, # from MAIL FROM:
15 $helo, # from HELO|EHLO
16 $myname, # optional: my hostname
17 { default_spf => 'mx/24 ?all' }
18 );
19 # could be other resolvers too
21 my $resolver = Net::DNS::Resolver->new;
22 ### with nonblocking, but still in loop
24 ### (callbacks are preferred with non-blocking)
25 my ($result,@ans) = $spf->next; # initial query
26 while ( ! $result ) {
27 my @query = @ans;
28 die "no queries" if ! @query;
29 for my $q (@query) {
30 # resolve query
31 my $socket = $resolver->bgsend( $q );
32 ... wait...
33 my $answer = $resolver->bgread($socket);
34 ($result,@ans) = $spf->next(
35 $answer # valid answer
36 || [ $q, $resolver->errorstring ] # or DNS problem
37 );
38 last if $result; # got final result
39 last if @ans; # got more DNS queries
40 }
41 }
42 ### OR with blocking:
44 ### ($result,@ans) = $spf->lookup_blocking( undef,$resolver );
45 ### print mailheader
47 print "Received-SPF: ".$spf->mailheader;
48 # $result = Fail|Pass|...
50 # $ans[0] = comment for Received-SPF
51 # $ans[1] = %hash with infos for Received-SPF
52 # $ans[2] = explanation in case of Fail
53
55 This module provides an iterative resolving of SPF records. Contrary to
56 Mail::SPF, which does blocking DNS lookups, this module just returns
57 the DNS queries and later expects the responses.
58 Lookup of the DNS records will be done outside of the module and can be
60 done in a event driven way.
61 This module can also make use of SenderID records for checking the
63 "mfrom" part, but only if it finds an SenderID record first (e.g. if
64 the SPF reply contains only SenderID and the the TXT SenderID and SPF
65 and it gets the SPF reply first it will use SenderID, if it gets TXT
66 first it will use SPF).
67 This behavior is not compatible with RFC4406 where SenderID records
69 take preference, but compatible with RFC4408 in that it uses SPF
70 records and provides a way to use SenderID if no SPF records are given.
71 See RFC4408 for SPF and RFC4406 for SenderID.
73
75 new( IP, MAILFROM, HELO, [ MYNAME ], [ \%OPT ] )
76 Construct a new Mail::SPF::Iterator object, which maintains the
77 state between the steps of the iteration. For each new SPF check a
78 new object has to be created.
79 IP is the IP if the client as string (IP4 or IP6).
81 MAILFROM is the user@domain part from the MAIL FROM handshake, e.g.
83 '<','>' and any parameters removed. If only '<>' was given (like in
84 bounces) the value is empty.
85 HELO is the string send within the HELO|EHLO dialog which should be
87 a domain according to the RFC but often is not.
88 MYNAME is the name of the local host. It's only used if required by
90 macros inside the SPF record.
91 OPT is used for additional arguments. Currently only default_spf is
93 expected which is used to set a default SPF record in case no
94 SPF/TXT records are returned from DNS (useful values are for
95 example 'mx ?all' or 'mx/24 ?all').
96 Returns the new object.
98 next([ ANSWER ])
100 "next" will be initially called with no arguments to get initial
101 DNS queries and then will be called with the DNS answers.
102 ANSWER is either a DNS packet with the response to a former query
104 or "[ QUERY, REASON ]" on failures, where QUERY is the DNS packet
105 containing the failed query and REASON the reason, why the query
106 failed (like TIMEOUT).
107 If a final result was achieved it will return "( RESULT, COMMENT,
109 HASH, EXPLAIN )". RESULT is the result, e.g. "Fail", "Pass",....
110 COMMENT is the comment for the Received-SPF header. HASH contains
111 information about problem, mechanism for the Received-SPF header.
112 EXPLAIN will be set to the explain string if RESULT is Fail.
113 If no final result was achieved yet it will either return
115 "(undef,@QUERIES)" with a list of new queries to continue, "('')"
116 in case the ANSWER produced an error but got ignored, because there
117 are other queries open, or "()" in case the ANSWER was ignored
118 because it did not match any open queries.
119 mailheader
121 Creates value for Received-SPF header based on the final answer
122 from next(). Returns header as string (one line, no folding) or
123 undef, if no final result was found. This creates only the value,
124 not the 'Received-SPF' prefix.
125 result
127 Returns ( RESULT, COMMENT, HASH, EXPLAIN ) like the final "next"
128 does or () if the final result wasn't found yet.
129 If the SPF record had an explain modifier, which needed DNS lookups
131 to resolve this method might return the result (although with
132 incomplete explain) before "next" does it.
133 explain_default ( [ EXPLAIN ] )
135 Sets default explanation string if EXPLAIN is given. If it's
136 called as a class method the default explanation string for the
137 class will be set, otherwise the default explanation string for the
138 object.
139 Returns the current default explanation string for the object or if
141 non given or if called as a class method the default explanation
142 string for the class.
143 lookup_blocking ( [ TIMEOUT, RESOLVER ] )
145 Quick way to get the SPF status. This will simply call "next"
146 until it gets a final result.
147 TIMEOUT limits the lookup time and defaults to 20. RESOLVER is a
149 Net::DNS::Resolver object (or similar) and defaults to
150 "Net::DNS::Resolver->new". Returns ( RESULT, COMMENT, HASH ) like
151 the final "next" does.
152 This is not the preferred way to use this module, because it's
154 blocking, so no lookups can be done in parallel in a single
155 process/thread.
156
158 For convenience the constants SPF_TempError, SPF_PermError, SPF_Pass,
159 SPF_Fail, SPF_SoftFail, SPF_Neutral, SPF_None are by default exported,
160 which have the values "TempError", "PermError" ...
161 Arguments to "use"/"import"
163 The "SPF_*" symbols are available for import and are exported if no
164 arguments are given to "use" or "import". Same effect with adding
165 ":DEFAULT" as an argument. Additionally the following arguments are
166 supported:
167 DebugFunc => \&coderef
169 Sets a custom debug function, which just takes on argument. If
170 given it will be called on all debug messages when debugging is
171 active. This function takes as the only argument the debug message.
172 Debug => 1|0
174 Switches debugging on/off.
175
177 Steffen Ullrich <sullr@cpan.org>
178
180 Copyright by Steffen Ullrich.
181 This module is free software; you can redistribute it and/or modify it
183 under the same terms as Perl itself.
184perl v5.28.0 2018-03-09 Mail::SPF::Iterator(3)