.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Mail::SPF::Server 3" .TH Mail::SPF::Server 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Mail::SPF::Server \- Server class for processing SPF requests .SH VERSION .IX Header "VERSION" version 3.20240827 .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Mail::SPF; \& \& my $spf_server = Mail::SPF::Server\->new( \& # Optional custom default for authority explanation: \& default_authority_explanation => \& \*(AqSee http://www.%{d}/why/id=%{S};ip=%{I};r=%{R}\*(Aq \& ); \& \& my $result = $spf_server\->process($request); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBMail::SPF::Server\fR is a server class for processing SPF requests. Each server instance can be configured with specific processing parameters. Also, the default \fINet::DNS::Resolver\fR DNS resolver used for making DNS look-ups can be overridden with a custom resolver object. .SS Constructor .IX Subsection "Constructor" The following constructor is provided: .IP "\fBnew(%options)\fR: returns \fIMail::SPF::Server\fR" 4 .IX Item "new(%options): returns Mail::SPF::Server" Creates a new server object for processing SPF requests. .Sp \&\f(CW%options\fR is a list of key/value pairs representing any of the following options: .RS 4 .IP \fBdefault_authority_explanation\fR 4 .IX Item "default_authority_explanation" A \fIstring\fR denoting the default (not macro-expanded) authority explanation string to use if the authority domain does not specify an explanation string of its own. Defaults to: .Sp .Vb 1 \& \*(AqPlease see http://www.openspf.org/Why?s=%{_scope};id=%{S};ip=%{C};r=%{R}\*(Aq .Ve .Sp As can be seen from the default, a non-standard \f(CW\*(C`_scope\*(C'\fR pseudo macro is supported that expands to the name of the identity's scope. (Note: Do \fInot\fR use any non-standard macros in explanation strings published in DNS.) .IP \fBhostname\fR 4 .IX Item "hostname" A \fIstring\fR denoting the local system's fully qualified host name that should be used for expanding the \f(CW\*(C`r\*(C'\fR macro in explanation strings. Defaults to the system's configured host name. .IP \fBdns_resolver\fR 4 .IX Item "dns_resolver" An optional DNS resolver object. If none is specified, a new \fINet::DNS::Resolver\fR object is used. The resolver object may be of a different class, but it must provide an interface similar to \fINet::DNS::Resolver\fR \-\- at least the \f(CW\*(C`send\*(C'\fR and \f(CW\*(C`errorstring\*(C'\fR methods must be supported, and the \f(CW\*(C`send\*(C'\fR method must return either an object of class \fINet::DNS::Packet\fR, or, in the case of an error, \fBundef\fR. .IP \fBquery_rr_types\fR 4 .IX Item "query_rr_types" For which RR types to query when looking up and selecting SPF records. The following values are supported: .RS 4 .IP \fBMail::SPF::Server\->query_rr_type_all\fR 4 .IX Item "Mail::SPF::Server->query_rr_type_all" Both \f(CW\*(C`TXT\*(C'\fR and \f(CW\*(C`SPF\*(C'\fR type RRs. .IP "\fBMail::SPF::Server\->query_rr_type_txt\fR (default)" 4 .IX Item "Mail::SPF::Server->query_rr_type_txt (default)" \&\f(CW\*(C`TXT\*(C'\fR type RRs only. .IP \fBMail::SPF::Server\->query_rr_type_spf\fR 4 .IX Item "Mail::SPF::Server->query_rr_type_spf" \&\f(CW\*(C`SPF\*(C'\fR type RRs only. .RE .RS 4 .Sp For years \fBMail::SPF\fR has defaulted to looking up both \f(CW\*(C`SPF\*(C'\fR and \f(CW\*(C`TXT\*(C'\fR type RRs as recommended by RFC 4408. Experience has shown, however, that a significant portion of name servers suffer from serious brain damage with regard to the handling of queries for RR types that are unknown to them, such as the \f(CW\*(C`SPF\*(C'\fR RR type. Consequently \fBMail::SPF\fR now defaults to looking up only \f(CW\*(C`TXT\*(C'\fR type RRs. This may be overridden by setting the \fBquery_rr_types\fR option. .Sp See RFC 4408, 3.1.1, for a discussion of the topic, as well as the description of the "select_record" method. .RE .IP \fBmax_dns_interactive_terms\fR 4 .IX Item "max_dns_interactive_terms" An \fIinteger\fR denoting the maximum number of terms (mechanisms and modifiers) per SPF check that perform DNS look-ups, as defined in RFC 4408, 10.1, paragraph 6. If \fBundef\fR is specified, there is no limit on the number of such terms. Defaults to \fB10\fR, which is the value defined in RFC 4408. .Sp A value above the default is \fIstrongly discouraged\fR for security reasons. A value below the default has implications with regard to the predictability of SPF results. Only deviate from the default if you know what you are doing! .IP \fBmax_name_lookups_per_term\fR 4 .IX Item "max_name_lookups_per_term" An \fIinteger\fR denoting the maximum number of DNS name look-ups per term (mechanism or modifier), as defined in RFC 4408, 10.1, paragraph 7. If \&\fBundef\fR is specified, there is no limit on the number of look-ups performed. Defaults to \fB10\fR, which is the value defined in RFC 4408. .Sp A value above the default is \fIstrongly discouraged\fR for security reasons. A value below the default has implications with regard to the predictability of SPF results. Only deviate from the default if you know what you are doing! .IP \fBmax_name_lookups_per_mx_mech\fR 4 .IX Item "max_name_lookups_per_mx_mech" .PD 0 .IP \fBmax_name_lookups_per_ptr_mech\fR 4 .IX Item "max_name_lookups_per_ptr_mech" .PD An \fIinteger\fR denoting the maximum number of DNS name look-ups per \fBmx\fR or \fBptr\fR mechanism, respectively. Defaults to the value of the \f(CW\*(C`max_name_lookups_per_term\*(C'\fR option. See there for additional information and security notes. .IP \fBmax_void_dns_lookups\fR 4 .IX Item "max_void_dns_lookups" An \fIinteger\fR denoting the maximum number of "void" DNS look-ups per SPF check, i.e. the number of DNS look-ups that were caused by DNS-interactive terms and macros (as defined in RFC 4408, 10.1, paragraphs 6 and 7) and that are allowed to return an empty answer with RCODE 0 or RCODE 3 (\f(CW\*(C`NXDOMAIN\*(C'\fR) before processing is aborted with a \f(CW\*(C`permerror\*(C'\fR result. If \fBundef\fR is specified, there is no stricter limit on the number of void DNS look-ups beyond the usual processing limits. Defaults to \fB2\fR. .Sp Specifically, the DNS look-ups that are subject to this limit are those caused by the \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`mx\*(C'\fR, \f(CW\*(C`ptr\*(C'\fR, and \f(CW\*(C`exists\*(C'\fR mechanisms and the \f(CW\*(C`p\*(C'\fR macro. .Sp A value of \fB2\fR is likely to prevent effective DoS attacks against third-party victim domains. However, a definite limit may cause \f(CW\*(C`permerror\*(C'\fR results even with certain (overly complex) innocent sender policies where useful results would normally be returned. .RE .RS 4 .RE .SS "Class methods" .IX Subsection "Class methods" The following class methods are provided: .IP "\fBresult_class\fR: returns \fIclass\fR" 4 .IX Item "result_class: returns class" .PD 0 .IP "\fBresult_class($name)\fR: returns \fIclass\fR" 4 .IX Item "result_class($name): returns class" .PD Returns a \fIMail::SPF::Result\fR descendent class determined from the given result name via the server's inherent result base class, or returns the server's inherent result base class if no result name is given. This method may also be used as an instance method. .Sp \&\fINote\fR: Do not write code invoking class methods on \fIliteral\fR result class names as this would ignore any derivative result classes provided by \&\fBMail::SPF\fR extension modules. .ie n .IP "\fBthrow_result($name, \fR\fB$request\fR\fB)\fR: throws \fIMail::SPF::Result\fR" 4 .el .IP "\fBthrow_result($name, \fR\f(CB$request\fR\fB)\fR: throws \fIMail::SPF::Result\fR" 4 .IX Item "throw_result($name, $request): throws Mail::SPF::Result" .PD 0 .ie n .IP "\fBthrow_result($name, \fR\fB$request\fR\fB, \fR\fB$text\fR\fB)\fR: throws \fIMail::SPF::Result\fR" 4 .el .IP "\fBthrow_result($name, \fR\f(CB$request\fR\fB, \fR\f(CB$text\fR\fB)\fR: throws \fIMail::SPF::Result\fR" 4 .IX Item "throw_result($name, $request, $text): throws Mail::SPF::Result" .PD Throws a \fIMail::SPF::Result\fR descendant determined from the given result name via the server's inherent result base class, passing an optional result text and associating the given \fIMail::SPF::Request\fR object with the result object. This method may also be used as an instance method. .Sp \&\fINote\fR: Do not write code invoking \f(CW\*(C`throw\*(C'\fR on \fIliteral\fR result class names as this would ignore any derivative result classes provided by \fBMail::SPF\fR extension modules. .SS "Instance methods" .IX Subsection "Instance methods" The following instance methods are provided: .IP "\fBprocess($request)\fR: returns \fIMail::SPF::Result\fR" 4 .IX Item "process($request): returns Mail::SPF::Result" Processes the given \fIMail::SPF::Request\fR object, queries the authoritative domain for an SPF sender policy (see the description of the "select_record" method), evaluates the policy with regard to the given identity and other request parameters, and returns a \fIMail::SPF::Result\fR object denoting the result of the policy evaluation. See RFC 4408, 4, and RFC 4406, 4, for details. .IP "\fBselect_record($request)\fR: returns \fIMail::SPF::Record\fR; throws \fIMail::SPF::EDNSError\fR, \fIMail::SPF::ENoAcceptableRecord\fR, \fIMail::SPF::ERedundantAcceptableRecords\fR, \fIMail::SPF::ESyntaxError\fR" 4 .IX Item "select_record($request): returns Mail::SPF::Record; throws Mail::SPF::EDNSError, Mail::SPF::ENoAcceptableRecord, Mail::SPF::ERedundantAcceptableRecords, Mail::SPF::ESyntaxError" Queries the authority domain of the given \fIMail::SPF::Request\fR object for SPF sender policy records and, if multiple records are available, selects the record of the highest acceptable record version that covers the requested scope. .Sp More precisely, the following algorithm is performed (assuming that both \f(CW\*(C`TXT\*(C'\fR and \f(CW\*(C`SPF\*(C'\fR RR types are being queried): .RS 4 .IP 1. 4 Determine the authority domain, the set of acceptable SPF record versions, and the identity scope from the given request object. .IP 2. 4 Query the authority domain for SPF records of the \f(CW\*(C`SPF\*(C'\fR DNS RR type, discarding any records that are of an inacceptable version or do not cover the desired scope. .Sp If this yields no SPF records, query the authority domain for SPF records of the \f(CW\*(C`TXT\*(C'\fR DNS RR type, discarding any records that are of an inacceptable version or do not cover the desired scope. .Sp If still no acceptable SPF records could be found, throw a \&\fIMail::SPF::ENoAcceptableRecord\fR exception. .IP 3. 4 Discard all records but those of the highest acceptable version found. .Sp If exactly one record remains, return it. Otherwise, throw a \&\fIMail::SPF::ERedundantAcceptableRecords\fR exception. .RE .RS 4 .Sp If the querying of either RR type has been disabled via the "new" constructor's \f(CW\*(C`query_rr_types\*(C'\fR option, the respective part in step 2 will be skipped. .Sp \&\fIMail::SPF::EDNSError\fR exceptions due to DNS look-ups and \&\fIMail::SPF::ESyntaxError\fR exceptions due to invalid acceptable records may also be thrown. .RE .ie n .IP "\fBget_acceptable_records_from_packet($packet, \fR\fB$rr_type\fR\fB, \e@versions, \fR\fB$scope\fR\fB, \fR\fB$domain\fR\fB)\fR: returns \fIlist\fR of \fIMail::SPF::Record\fR" 4 .el .IP "\fBget_acceptable_records_from_packet($packet, \fR\f(CB$rr_type\fR\fB, \e@versions, \fR\f(CB$scope\fR\fB, \fR\f(CB$domain\fR\fB)\fR: returns \fIlist\fR of \fIMail::SPF::Record\fR" 4 .IX Item "get_acceptable_records_from_packet($packet, $rr_type, @versions, $scope, $domain): returns list of Mail::SPF::Record" Filters from the given \fINet::DNS::Packet\fR object all resource records of the given RR type and for the given domain name, discarding any records that are not SPF records at all, that are of an inacceptable SPF record version, or that do not cover the given scope. Returns a list of acceptable records. .ie n .IP "\fBdns_lookup($domain, \fR\fB$rr_type\fR\fB)\fR: returns \fINet::DNS::Packet\fR; throws \fIMail::SPF::EDNSTimeout\fR, \fIMail::SPF::EDNSError\fR" 4 .el .IP "\fBdns_lookup($domain, \fR\f(CB$rr_type\fR\fB)\fR: returns \fINet::DNS::Packet\fR; throws \fIMail::SPF::EDNSTimeout\fR, \fIMail::SPF::EDNSError\fR" 4 .IX Item "dns_lookup($domain, $rr_type): returns Net::DNS::Packet; throws Mail::SPF::EDNSTimeout, Mail::SPF::EDNSError" Queries the DNS using the configured resolver for resource records of the desired type at the specified domain and returns a \fINet::DNS::Packet\fR object if an answer packet was received. Throws a \fIMail::SPF::EDNSTimeout\fR exception if a DNS time-out occurred. Throws a \fIMail::SPF::EDNSError\fR exception if an error (other than RCODE 3 AKA \f(CW\*(C`NXDOMAIN\*(C'\fR) occurred. .IP "\fBcount_dns_interactive_term($request)\fR: throws \fIMail::SPF::EProcessingLimitExceeded\fR" 4 .IX Item "count_dns_interactive_term($request): throws Mail::SPF::EProcessingLimitExceeded" Increments by one the count of DNS-interactive mechanisms and modifiers that have been processed so far during the evaluation of the given \&\fIMail::SPF::Request\fR object. If this exceeds the configured limit (see the "new" constructor's \f(CW\*(C`max_dns_interactive_terms\*(C'\fR option), throws a \&\fIMail::SPF::EProcessingLimitExceeded\fR exception. .Sp This method is supposed to be called by the \f(CW\*(C`match\*(C'\fR and \f(CW\*(C`process\*(C'\fR methods of \&\fIMail::SPF::Mech\fR and \fIMail::SPF::Mod\fR sub-classes before (and only if) they do any DNS look-ups. .IP "\fBcount_void_dns_lookup($request)\fR: throws \fIMail::SPF::EProcessingLimitExceeded\fR" 4 .IX Item "count_void_dns_lookup($request): throws Mail::SPF::EProcessingLimitExceeded" Increments by one the count of "void" DNS look-ups that have occurred so far during the evaluation of the given \fIMail::SPF::Request\fR object. If this exceeds the configured limit (see the "new" constructor's \f(CW\*(C`max_void_dns_lookups\*(C'\fR option), throws a \fIMail::SPF::EProcessingLimitExceeded\fR exception. .Sp This method is supposed to be called by any code after any calls to the "dns_lookup" method whenever (i) no answer records were returned, and (ii) this fact is a possible indication of a DoS attack against a third-party victim domain, and (iii) the number of "void" look-ups is not already constrained otherwise (as for example is the case with the \f(CW\*(C`include\*(C'\fR mechanism and the \&\f(CW\*(C`redirect\*(C'\fR modifier). Specifically, this applies to look-ups performed by the \&\f(CW\*(C`a\*(C'\fR, \f(CW\*(C`mx\*(C'\fR, \f(CW\*(C`ptr\*(C'\fR, and \f(CW\*(C`exists\*(C'\fR mechanisms and the \f(CW\*(C`p\*(C'\fR macro. .IP "\fBdefault_authority_explanation\fR: returns \fIMail::SPF::MacroString\fR" 4 .IX Item "default_authority_explanation: returns Mail::SPF::MacroString" Returns the default authority explanation as a \fIMacroString\fR object. See the description of the "new" constructor's \f(CW\*(C`default_authority_explanation\*(C'\fR option. .IP "\fBhostname\fR: returns \fIstring\fR" 4 .IX Item "hostname: returns string" Returns the local system's host name. See the description of the "new" constructor's \f(CW\*(C`hostname\*(C'\fR option. .IP "\fBdns_resolver\fR: returns \fINet::DNS::Resolver\fR or compatible object" 4 .IX Item "dns_resolver: returns Net::DNS::Resolver or compatible object" Returns the DNS resolver object of the server object. See the description of the "new" constructor's \f(CW\*(C`dns_resolver\*(C'\fR option. .IP "\fBquery_rr_types\fR: returns \fIinteger\fR" 4 .IX Item "query_rr_types: returns integer" Returns a value denoting the RR types for which to query when looking up and selecting SPF records. See the description of the "new" constructor's \&\f(CW\*(C`query_rr_types\*(C'\fR option. .IP "\fBmax_dns_interactive_terms\fR: returns \fIinteger\fR" 4 .IX Item "max_dns_interactive_terms: returns integer" .PD 0 .IP "\fBmax_name_lookups_per_term\fR: returns \fIinteger\fR" 4 .IX Item "max_name_lookups_per_term: returns integer" .IP "\fBmax_name_lookups_per_mx_mech\fR: returns \fIinteger\fR" 4 .IX Item "max_name_lookups_per_mx_mech: returns integer" .IP "\fBmax_name_lookups_per_ptr_mech\fR: returns \fIinteger\fR" 4 .IX Item "max_name_lookups_per_ptr_mech: returns integer" .IP "\fBmax_void_dns_lookups\fR: returns \fIinteger\fR" 4 .IX Item "max_void_dns_lookups: returns integer" .PD Return the limit values of the server object. See the description of the "new" constructor's corresponding options. .SH "SEE ALSO" .IX Header "SEE ALSO" Mail::SPF, Mail::SPF::Request, Mail::SPF::Result .PP .PP For availability, support, and license information, see the README file included with Mail::SPF. .SH AUTHORS .IX Header "AUTHORS" Julian Mehnle , Shevek