MailAuth.DKIM (MailAuth v0.1.0)

Copy Markdown View Source

DKIM signatures (RFC 6376), with the algorithm rules of RFC 8301 and Ed25519 keys (RFC 8463).

verify/2 checks every DKIM-Signature header of a message. sign/2 adds one or more. generate_key/2 makes a key and the TXT record to publish.

Verify options

  • :max_signatures: how many signatures to check, in order. Default 5. The rest are :none, reason :too_many_signatures
  • :min_key_bits: the smallest RSA key that can pass. Default 1024
  • :allow_sha1: when true, an rsa-sha1 signature can pass, with the warning :weak_algorithm. Default false
  • :now: the time to check x= against, in Unix seconds or a DateTime. Default: now
  • :resolver, :deadline, :timeout: see MailAuth.Resolver and MailAuth

Signer options

  • :domain (required): the signing domain, d=
  • :selector (required): the selector, s=
  • :private_key (required): PEM, a decoded :public_key record, or {:ed25519, seed}
  • :algorithm: :rsa_sha256 or :ed25519_sha256. Default: from the key
  • :canonicalization: default {:relaxed, :relaxed}
  • :headers: the header names to sign. Each is signed as many times as it appears. Default: default_headers/0
  • :oversign: names listed once more than they appear, so no one can add another. Default ["From", "Subject", "To", "Date"]
  • :identity: the i= tag
  • :expires_in: seconds until the signature expires, for x=
  • :body_length: when true, sets l= to the length of the body. Unsafe: anyone can add text after the signed part. Default false
  • :now: the signing time, for t=

Summary

Functions

default_headers()

The headers signed by default.

generate_key(type \\ :rsa, opts \\ [])

Generates a DKIM key: RSA (2048 bits by default) or Ed25519.

sign(raw, signer_opts)

Signs raw and returns it with the new DKIM-Signature header on top.

signature_header(raw, opts)

Returns the DKIM-Signature header for raw, without a final line break.

verify(raw, opts \\ [])

Checks every DKIM-Signature header of raw, top to bottom.

Functions

default_headers()

@spec default_headers() :: [String.t()]

The headers signed by default.

generate_key(type \\ :rsa, opts \\ [])

@spec generate_key(:rsa | :ed25519, keyword()) :: %{
  :private_key => String.t(),
  :dns_record => String.t(),
  optional(:dns_name) => String.t()
}

Generates a DKIM key: RSA (2048 bits by default) or Ed25519.

Returns the private key as PEM and the TXT record to publish. With :selector and :domain given, also returns the name to publish it at, <selector>._domainkey.<domain>.

Options: :bits (RSA only), :selector, :domain.

sign(raw, signer_opts)

@spec sign(binary(), keyword() | [keyword()]) :: {:ok, binary()} | {:error, atom()}

Signs raw and returns it with the new DKIM-Signature header on top.

Pass a list of signer options to add several signatures at once, such as an RSA and an Ed25519 one. The first in the list ends up on top.

signature_header(raw, opts)

@spec signature_header(binary(), keyword()) :: {:ok, String.t()} | {:error, atom()}

Returns the DKIM-Signature header for raw, without a final line break.

verify(raw, opts \\ [])

@spec verify(binary(), keyword()) :: [MailAuth.DKIM.Result.t()]

Checks every DKIM-Signature header of raw, top to bottom.

Returns one result per signature, in the order they appear. A message with no signature gives [].