1Mail::SPF::Request(3) User Contributed Perl DocumentationMail::SPF::Request(3)
2
3
4

NAME

6       Mail::SPF::Request - SPF request class
7

SYNOPSIS

9           use Mail::SPF;
10
11           my $request = Mail::SPF::Request->new(
12               versions    => [1, 2],              # optional
13               scope       => 'mfrom',             # or 'helo', 'pra'
14               identity    => 'fred@example.com',
15               ip_address  => '192.168.0.1',
16               helo_identity                       # optional,
17                           => 'mta.example.com'    #   for %{h} macro expansion
18           );
19
20           my @versions    = $request->versions;
21           my $scope       = $request->scope;
22           my $authority_domain
23                           = $request->authority_domain;
24           my $identity    = $request->identity;   # 'localpart@domain' or 'domain'
25           my $domain      = $request->domain;
26           my $localpart   = $request->localpart;
27           my $ip_address  = $request->ip_address;     # IPv4 or IPv6 address
28           my $ip_address_v6                           # native IPv6 address or
29                           = $request->ip_address_v6;  #   IPv4-mapped IPv6 address
30           my $helo_identity                           # additional HELO identity
31                           = $request->helo_identity;  #   for non-HELO scopes
32
33           my $record      = $request->record;
34               # the record selected during processing of the request, may be undef
35
36           $request->state(field => 'value');
37           my $value = $request->state('field');
38

DESCRIPTION

40       An object of class Mail::SPF::Request represents an SPF request.
41
42   Constructors
43       The following constructors are provided:
44
45       new(%options): returns Mail::SPF::Request
46           Creates a new SPF request object.  The request is considered the
47           root-request for any subsequent sub-requests (see the
48           "new_sub_request" constructor).
49
50           %options is a list of key/value pairs representing any of the
51           following options:
52
53           versions
54               A reference to an array of integers listing the versions of SPF
55               records that may be used for the SPF check.  Only those record
56               versions that cover the desired scope will actually be used.
57               At least one applicable version must be specified.  For a
58               single record version, a simple scalar may be specified instead
59               of an array-ref.  Defaults to all versions that cover the
60               desired scope (see below); defaults to [1, 2] for the default
61               scope of 'mfrom'.
62
63               The following versions are supported:
64
65               1   Use "v=spf1" records.
66
67               2   Use "spf2.0" records.
68
69               Example:  A value of 1 (or [1]) means that only "v=spf1"
70               records should be used for the SPF check.  If at the same time
71               a scope of 'pra' is specified, a Mail::SPF::EInvalidScope
72               exception will be thrown as "v=spf1" records do not cover the
73               PRA scope.
74
75           scope
76               A string denoting the authorization scope of the identity that
77               should be checked.  Defaults to 'mfrom'.  The following scope
78               values are supported:
79
80               'helo'
81                   The given identity is the "HELO" parameter of an SMTP
82                   transaction (RFC 2821) and should be checked against SPF
83                   records that cover the "helo" scope ("v=spf1").  See the
84                   SPFv1 specification (RFC 4408) for the formal definition of
85                   the "HELO" scope.
86
87               'mfrom'
88                   The given identity is the "MAIL FROM" parameter of an SMTP
89                   transaction (RFC 2821), and should be checked against SPF
90                   records that cover the "mfrom" scope ("v=spf1" and
91                   "spf2.0/mfrom").  See the SPFv1 specification (RFC 4408)
92                   for the formal definition of the "MAIL FROM" scope.
93
94                   Note:  In the case of an empty "MAIL FROM" SMTP transaction
95                   parameter ("MAIL FROM:<>"), you should perform a check with
96                   the "helo" scope instead.
97
98               'pra'
99                   The given identity is the "Purported Responsible Address"
100                   of an internet message (RFC 2822) and should be checked
101                   against SPF records that cover the "pra" scope
102                   ("spf2.0/pra").  See the PRA specification (RFC 4407) for
103                   the formal definition of the PRA scope.
104
105           authority_domain
106               A string denoting the domain name that should be queried for
107               sender policy records.  Defaults to the domain of the
108               "identity" option.  There is usually no need to specify the
109               "authority_domain" option.
110
111           identity
112               Required.  A string denoting the sender identity whose
113               authorization should be checked.  This is a domain name for the
114               "helo" scope, and an e-mail address for the "mfrom" and "pra"
115               scopes.
116
117               Note:  An empty identity must not be passed.  In the case of an
118               empty "MAIL FROM" SMTP transaction parameter, you should
119               perform a check with the "helo" scope instead.
120
121           ip_address
122               Required for checks with the "helo", "mfrom", and "pra" scopes.
123               Either a string or a NetAddr::IP object denoting the IP address
124               of the host claiming the identity that is being checked.  Can
125               be either an IPv4 or an IPv6 address.  An IPv4-mapped IPv6
126               address (e.g. '::ffff:192.168.0.1') is treated as an IPv4
127               address.
128
129           helo_identity
130               A string denoting the "HELO" SMTP transaction parameter in the
131               case that the main identity is of a scope other than "helo".
132               This identity is then used merely for the expansion of "%{h}"
133               macros during the policy evaluation of the main identity.
134               Defaults to undef, which will be expanded to 'unknown'.  If the
135               main identity is of the "helo" scope, this option is unused.
136
137       new_sub_request(%options): returns Mail::SPF::Request
138           Must be invoked on an existing request object.  Creates a new sub-
139           request object by cloning the invoked request, which is then
140           considered the new request's super-request.  Any specified options
141           (see the "new" constructor) override the parameters of the super-
142           request.  There is usually no need to specify any options besides
143           the "authority_domain" option.
144
145   Instance methods
146       The following instance methods are provided:
147
148       root_request: returns Mail::SPF::Request
149           Returns the root of the request's chain of super-requests.
150           Specifically, returns the request itself if it has no super-
151           requests.
152
153       super_request: returns Mail::SPF::Request
154           Returns the super-request of the request, or undef if there is
155           none.
156
157       versions: returns list of string
158           Returns a list of the SPF record versions that are used for
159           request.  See the description of the "new" constructor's "versions"
160           option.
161
162       scope: returns string
163           Returns the scope of the request.  See the description of the "new"
164           constructor's "scope" option.
165
166       authority_domain: returns string
167           Returns the authority domain of the request.  See the description
168           of the "new" constructor's "authority_domain" option.
169
170       identity: returns string
171           Returns the identity of the request.  See the description of the
172           "new" constructor's "identity" option.
173
174       domain: returns string
175           Returns the identity domain of the request.  See the description of
176           the "new" constructor's "identity" option.
177
178       localpart: returns string
179           Returns the identity localpart of the request.  See the description
180           of the "new" constructor's "identity" option.
181
182       ip_address: returns NetAddr::IP
183           Returns the IP address of the request as a NetAddr::IP object.  See
184           the description of the "new" constructor's "ip_address" option.
185
186       ip_address_v6: returns NetAddr::IP
187           Like the "ip_address" method, however, an IPv4 address is returned
188           as an IPv4-mapped IPv6 address (e.g. '::ffff:192.168.0.1') to
189           facilitate uniform processing.
190
191       helo_identity: returns string
192           Returns the "HELO" SMTP transaction parameter of the request.  See
193           the description of the "new" constructor's "helo_identity" option.
194
195       record: returns Mail::SPF::Record
196           Returns the SPF record selected during the processing of the
197           request, or undef if there is none.
198
199       state($field): returns anything
200       state($field, $value): returns anything
201           Provides an interface for storing temporary state information with
202           the request object.  This is primarily meant to be used internally
203           by Mail::SPF::Server and other Mail::SPF classes.
204
205           If $value is specified, stores it in a state field named $field.
206           Returns the current (new) value of the state field named $field.
207           This method may be used as an lvalue.
208

SEE ALSO

210       Mail::SPF, Mail::SPF::Server
211
212       <http://tools.ietf.org/html/rfc4408>
213
214       For availability, support, and license information, see the README file
215       included with Mail::SPF.
216

AUTHORS

218       Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
219
220
221
222perl v5.34.0                      2022-01-21             Mail::SPF::Request(3)
Impressum