Sovite.DKIM (sovite v0.6.0)

Copy Markdown View Source

DKIM signing and verification (RFC 6376), with RSA-SHA256 and Ed25519-SHA256 (RFC 8463). RSA-SHA1 signatures and RSA keys shorter than 1024 bits are never accepted (RFC 8301).

For a whole message in memory:

results = Sovite.DKIM.verify(message, resolver)
[field] = Sovite.DKIM.sign(message, [key])
signed = field <> message

An MTA hashes the body while it streams by instead: see Sovite.DKIM.Verifier and sign_fields/4, with Sovite.DKIM.Body.

Header fields are as returned by Sovite.Message.Headers.parse/1. Signing always uses relaxed/relaxed canonicalization.

Telemetry

  • [:sovite, :dkim, :verify] - %{count: signatures}, %{results: [result]}, once per message verified.

Summary

Functions

body_spec()

The body hash sign_fields/4 needs: relaxed, SHA-256, whole body.

default_headers()

The header fields signed by default, when present.

sign(message, keys, opts \\ [])

Signs message with each key, for dual signing (RSA and Ed25519). Returns the DKIM-Signature: fields to put at the top of the message, in the order of keys. Options are those of sign_fields/4.

sign_fields(fields, body_hash, key, opts \\ [])

Builds a signed DKIM-Signature: field (with CRLF) for header fields and the body hash for body_spec/0.

verify(message, resolver, opts \\ [])

Verifies every DKIM-Signature: of message (header and body, CRLF line endings). Options are those of Sovite.DKIM.Verifier.new/2.

Functions

body_spec()

@spec body_spec() :: Sovite.DKIM.Body.spec()

The body hash sign_fields/4 needs: relaxed, SHA-256, whole body.

default_headers()

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

The header fields signed by default, when present.

sign(message, keys, opts \\ [])

@spec sign(binary(), [Sovite.DKIM.SigningKey.t()], keyword()) :: [String.t()]

Signs message with each key, for dual signing (RSA and Ed25519). Returns the DKIM-Signature: fields to put at the top of the message, in the order of keys. Options are those of sign_fields/4.

sign_fields(fields, body_hash, key, opts \\ [])

@spec sign_fields(
  [Sovite.Message.Headers.field()],
  binary(),
  Sovite.DKIM.SigningKey.t(),
  keyword()
) ::
  String.t()

Builds a signed DKIM-Signature: field (with CRLF) for header fields and the body hash for body_spec/0.

Options

  • :headers - names of the fields to sign when present. Defaults to default_headers/0.
  • :oversign - names signed once more than they occur, so no instance can be added later. Defaults to ["from"].
  • :timestamp - Unix seconds for t=. Defaults to now.
  • :expiration - seconds after t= for x=. None by default.
  • :identity - the i= value. None by default.

verify(message, resolver, opts \\ [])

@spec verify(binary(), Sovite.DNS.resolver(), keyword()) :: [Sovite.DKIM.Result.t()]

Verifies every DKIM-Signature: of message (header and body, CRLF line endings). Options are those of Sovite.DKIM.Verifier.new/2.