[−][src]Function viaspf::evaluate_spf

pub fn evaluate_spf(
    lookup: &impl Lookup, 
    config: &Config, 
    ip: IpAddr, 
    sender: &str, 
    helo_domain: &str
) -> QueryResult

Performs an SPF query and evaluation.

Arguments:

  • lookup – an implementation of the Lookup trait, serving as a DNS resolver
  • config – a configuration object
  • ip – the client IP address. This corresponds to the <ip> argument in RFC 7208.
  • sender – the sender identity. This corresponds to both the <sender> and <domain> (= the domain part of <sender>) arguments in RFC 7208; see the discussion below.
  • helo_domain – the HELO/EHLO domain, used only for the %{h} macro

The return type QueryResult always conveys an SPF result, and, if available, additional diagnostic information.

This function corresponds to the function check_host() of RFC 7208, as is evident in the final three arguments ip, sender, and helo_domain. However, the correspondence is not exact. The ip argument matches <ip>. The sender argument covers both <sender> and <domain>, since <domain> can be mechanically derived from <sender>. Finally, helo_domain covers an argument missing in check_host(), namely, the %{h} macro, which always evaluates to the HELO domain.

The arguments sender and helo_domain are of type string slice. This is a somewhat ‘weak’ type in the sense that it allows a broad range of valid and invalid inputs. Now, according to the specification, an evaluation can only be performed when the domain of the sender identity is a valid, fully-qualified domain name, else the result none is returned. In other words, a valid sender is a prerequisite for an SPF query. For this reason, this function validates the sender argument eagerly at the beginning. The helo_domain argument, on the other hand, which is used only for the %{h} macro, is only validated when it is encountered during macro expansion, as it rarely occurs in practice and should not impede executing the SPF query. This aspect of the API is a bit subtle, and clients who need more control over these inputs are advised to do their own validation beforehand.

According with RFC 8616, internationalised domain names must be converted to their ASCII representation before executing the SPF query. The evaluate_spf function accepts both ASCII and Unicode-encoded inputs, and will in any case properly apply the IDNA algorithm with Punycode encoding. Internationalised email addresses and domain names may therefore be passed in directly in Unicode format.

Examples

The following examples illustrate usage of this function for SPF verification of a host.

Verifying the HELO identity

When verifying the HELO/EHLO identity, the client host presents some hostname with the HELO or EHLO SMTP command, for example, mail.example.org.

Pass this string as both the sender and helo_domain argument.

let result = evaluate_spf(&lookup, &config, ip, "mail.example.org", "mail.example.org");

In the terms of the check_host() function specification,

  • <domain> will then be the sender identity, that is mail.example.org;
  • <sender> itself gets qualified with the local part postmaster (see section 4.3 in the RFC) to become postmaster@mail.example.org.

Verifying the MAIL FROM identity

When verifying the MAIL FROM identity, the client host presents some email address with the MAIL FROM SMTP command, for example, amy@example.org. Before that, it will also have presented some HELO/EHLO hostname, for example, mail.example.org.

Pass these strings as the sender and helo_domain argument, respectively.

let result = evaluate_spf(&lookup, &config, ip, "amy@example.org", "mail.example.org");

In the terms of the check_host() function specification,

  • <domain> will then be the domain part of the sender identity, that is example.org;
  • <sender> will be the sender identity, that is amy@example.org.