Sovite.SPF (sovite v0.6.0)

Copy Markdown View Source

SPF verification (RFC 7208).

Sovite.SPF.check_mail_from(resolver, {192, 0, 2, 3}, "alice@example.com", "mx.example.com")
#=> %Sovite.SPF.Result{result: :pass, domain: "example.com", mechanism: "ip4:192.0.2.0/24"}

check_host/5 is the check_host() function of RFC 7208 §4. check_mail_from/5 and check_helo/4 pick the identity to check from the SMTP session (§2.3, §2.4).

DNS errors give :temperror. Records that cannot be parsed, too many DNS lookups, and includes or redirects to domains without an SPF record give :permerror. The lookup limits span the whole check, including nested include: and redirect= records.

Options

  • :helo - the HELO/EHLO name, for the h macro. check_mail_from/5 and check_helo/4 set it.
  • :receiver - this host's name, for the r macro in explanations. Defaults to "unknown".
  • :max_lookups - terms that query DNS (include, a, mx, ptr, exists, redirect, and the p macro). Defaults to 10.
  • :max_void_lookups - lookups by those terms that find no records. Defaults to 2.
  • :timeout - milliseconds for the whole check, after which the result is :temperror. Defaults to 20 seconds.
  • :now - Unix seconds for the t macro. Defaults to the current time.

Telemetry

  • [:sovite, :spf, :check, :start] - %{system_time}, %{domain, ip}
  • [:sovite, :spf, :check, :stop] - %{duration}, %{domain, ip, result}
  • [:sovite, :spf, :check, :exception] - the usual :telemetry.span/3 measurements and metadata

Summary

Types

result()

An SPF result (RFC 7208 §2.6).

Functions

check_helo(resolver, ip, helo, opts \\ [])

Checks the HELO identity (RFC 7208 §2.3), with postmaster@<helo> as the sender.

check_host(resolver, ip, domain, sender, opts \\ [])

Checks whether ip may send mail for domain, with sender as the MAIL FROM address (RFC 7208 §4). A sender without a local part gets "postmaster".

check_mail_from(resolver, ip, sender, helo, opts \\ [])

Checks the MAIL FROM identity (RFC 7208 §2.4).

Types

result()

@type result() ::
  :pass | :fail | :softfail | :neutral | :none | :temperror | :permerror

An SPF result (RFC 7208 §2.6).

Functions

check_helo(resolver, ip, helo, opts \\ [])

@spec check_helo(
  Sovite.DNS.resolver(),
  :inet.ip_address(),
  String.t() | nil,
  keyword()
) ::
  Sovite.SPF.Result.t()

Checks the HELO identity (RFC 7208 §2.3), with postmaster@<helo> as the sender.

An address literal or a name that is not a fully qualified domain name gives :none without any lookups.

check_host(resolver, ip, domain, sender, opts \\ [])

@spec check_host(
  Sovite.DNS.resolver(),
  :inet.ip_address(),
  String.t(),
  String.t(),
  keyword()
) ::
  Sovite.SPF.Result.t()

Checks whether ip may send mail for domain, with sender as the MAIL FROM address (RFC 7208 §4). A sender without a local part gets "postmaster".

A malformed domain gives :none without any lookups. See the module documentation for options.

check_mail_from(resolver, ip, sender, helo, opts \\ [])

@spec check_mail_from(
  Sovite.DNS.resolver(),
  :inet.ip_address(),
  String.t(),
  String.t() | nil,
  keyword()
) :: Sovite.SPF.Result.t()

Checks the MAIL FROM identity (RFC 7208 §2.4).

The domain checked is the domain of sender. For the null reverse-path (sender is ""), it is helo, with postmaster@<helo> as the sender.