1Mail::SPF::Request(3) User Contributed Perl DocumentationMail::SPF::Request(3)
2
6 Mail::SPF::Request - SPF request class
7
9 use Mail::SPF;
10 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 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 my $record = $request->record;
34 # the record selected during processing of the request, may be undef
35 $request->state(field => 'value');
37 my $value = $request->state('field');
38
40 An object of class Mail::SPF::Request represents an SPF request.
41 Constructors
43 The following constructors are provided:
44 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 %options is a list of key/value pairs representing any of the
51 following options:
52 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 The following versions are supported:
64 1 Use "v=spf1" records.
66 2 Use "spf2.0" records.
68 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 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 '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 '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 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 '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 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 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 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 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 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 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 Instance methods
146 The following instance methods are provided:
147 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 super_request: returns Mail::SPF::Request
154 Returns the super-request of the request, or undef if there is
155 none.
156 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 scope: returns string
163 Returns the scope of the request. See the description of the "new"
164 constructor's "scope" option.
165 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 identity: returns string
171 Returns the identity of the request. See the description of the
172 "new" constructor's "identity" option.
173 domain: returns string
175 Returns the identity domain of the request. See the description of
176 the "new" constructor's "identity" option.
177 localpart: returns string
179 Returns the identity localpart of the request. See the description
180 of the "new" constructor's "identity" option.
181 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 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 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 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 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 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
210 Mail::SPF, Mail::SPF::Server
211 <http://tools.ietf.org/html/rfc4408>
213 For availability, support, and license information, see the README file
215 included with Mail::SPF.
216
218 Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
219perl v5.34.0 2022-01-21 Mail::SPF::Request(3)