MailAuth

Checks whether an email really came from who it says. MailAuth verifies DKIM signatures, SPF and DMARC, signs mail with DKIM, and reads and writes Authentication-Results: headers. It works on mail received over SMTP and on mail read later over IMAP.

ARC (RFC 8617) is not implemented: the IETF is moving it to Historic, and DKIM2 is meant to replace it.

Installation

def deps do
  [
    {:mail_auth, "~> 0.1"}
  ]
end

MailAuth needs Elixir 1.18 or newer. It has no NIFs: it uses OTP's :crypto, :public_key and :inet_res.

Why

The From: line of an email proves nothing. Neither does the Authentication-Results: header that the receiving server adds: anyone can write one, and some servers write it without their name. A DKIM signature is part of the message and can still be checked after the message is stored. MailAuth checks it, then checks that the signing domain matches the From: domain under the domain's DMARC record. That gives a DMARC pass without trusting any header.

Usage

Mail read over IMAP

A help desk or a shared inbox reads mail long after it arrived. There is no client IP, so SPF can't run; DKIM and DMARC can.

result = MailAuth.authenticate(raw)

if MailAuth.Result.dmarc_pass?(result) do
  # The From: domain sent this message. Check result.dkim for the
  # :body_length_limit warning before trusting text near the end of the body.
end

raw is the message exactly as stored, headers and body. Lines end in CRLF; a message with bare LF line endings is read as if each LF were CRLF.

An SMTP server

An SMTP server, such as one built on gen_smtp, knows the client IP, so SPF runs too:

result = MailAuth.authenticate(raw, ip: peer_ip, mail_from: from, helo: helo)
header = MailAuth.AuthenticationResults.format(result, "mx.example.com")
# Add the header to the message before delivering it.

DNS

Every check reads DNS through a resolver, chosen with the :resolver option:

• MailAuth.Resolver.Inet, the default, asks DNS servers with :inet_res

• MailAuth.Resolver.Cached keeps answers in ETS for their TTL, "no such record" answers too. Start it in your supervision tree when you see much mail from the same domains:

  children = [{MailAuth.Resolver.Cached, resolver: MailAuth.Resolver.Inet}]
  MailAuth.authenticate(raw, resolver: MailAuth.Resolver.Cached)

• MailAuth.Resolver.Static answers from a map, for your tests:

  records = %{
    "s1._domainkey.example.com" => [txt: "v=DKIM1; p=MIGfMA0G..."],
    "_dmarc.example.com" => [txt: "v=DMARC1; p=reject"]
  }
  
  MailAuth.authenticate(raw, resolver: MailAuth.Resolver.Static, records: records)

Options

Every function takes:

• :resolver: see above
• :deadline: milliseconds for the whole call. Default 15000. A check still waiting on DNS at the deadline is :temperror, reason :deadline
• :timeout: milliseconds per DNS query. Default 5000
• :now: the time to check signatures against. Default: now

DKIM: :max_signatures (default 5), :min_key_bits (default 1024), :allow_sha1 (default false).

DMARC: :organizational_domain, a function (domain, opts) -> {:ok, org} | {:error, reason} used instead of the tree walk, for a caller who wants Public Suffix List answers.

SPF: :receiver, the name of your host, for the %{r} macro and Received-SPF:.

Signing

%{private_key: pem, dns_record: txt, dns_name: name} =
  MailAuth.DKIM.generate_key(:rsa, domain: "example.com", selector: "s1")

# Publish `txt` as a TXT record at `name`, then:
{:ok, signed} = MailAuth.DKIM.sign(raw, domain: "example.com", selector: "s1", private_key: pem)

Pass a list of signer options to sign with an RSA and an Ed25519 key at once. From, Subject, To and Date are oversigned by default, so no one can add a second one.

Results

Results use the words of RFC 8601: :pass, :fail, :neutral, :none, :temperror, :permerror, and :softfail for SPF. Each result has a reason, when it did not pass, and a list of warnings.

Reasons

Warnings

What a pass means

• A pass proves the domain, not the person. For gmail.com it means Google says the user signed in. For a domain that relays mail for many people it proves less.
• DNSSEC is not checked. Someone who can change DNS answers on the way can fake a pass.
• Replay. A real signed email can be sent again by someone else, to someone else, unless To: was signed. A pass says the domain wrote it, not that it was meant for this mailbox. The :to_not_signed warning helps; if you care, check To: and Date: yourself.
• l=. With a body length limit, anyone can add text after the signed part. Look for the :body_length_limit warning. Don't sign with body_length: true.
• Mailing lists and forwarding usually break DKIM. That is a :fail, which is the safe outcome.
• disposition is what the domain asks you to do with a failing message. MailAuth reports it and never acts on it.

Command-line tools

These are mix tasks, so they work wherever MailAuth is a dependency:

mix mail_auth.verify message.eml [--ip 192.0.2.1 --mail-from a@example.com --helo mx.example.com] [--json]
mix mail_auth.sign message.eml --domain example.com --selector s1 --key key.pem
mix mail_auth.dmarc example.com
mix mail_auth.spf example.com 192.0.2.1
mix mail_auth.gen_key --domain example.com --selector s1 [--ed25519]

--dns-file records.txt answers DNS from a file instead of the network, one record per line (name TYPE value), to check a message offline.

Telemetry

MailAuth emits :telemetry spans for [:mail_auth, :authenticate], [:mail_auth, :dkim, :verify], [:mail_auth, :dmarc], [:mail_auth, :spf] and [:mail_auth, :dns, :lookup], with the results and the time taken. They never include message content or keys.