Sovite.TLS.DANE (sovite v0.2.0)

DANE certificate verification for SMTP (RFC 6698, RFC 7671, RFC 7672).

A TLSA record is {usage, selector, matching_type, data}:

usage 3 (DANE-EE) - the server's own certificate or key. Its name, dates, and issuer are not checked (RFC 7672 §3.1.1).
usage 2 (DANE-TA) - a CA certificate or key in the chain the server sends; the chain from it must be valid for the server's name.
usages 0 and 1 (PKIX-TA, PKIX-EE) are not used for SMTP (RFC 7672 §3.1.3) and are ignored.
selector 0 matches the whole certificate, 1 its public key.
matching type 0 is the exact data, 1 SHA-256, 2 SHA-512.

Only records from a DNSSEC-authenticated answer may be used: see Sovite.DNS.lookup_secure/3.

Summary

Functions

client_options(records, hostname, tls \\ [])

Returns :ssl client options that accept a server only if its certificate chain matches one of records (already filtered with usable/1). hostname is the name the chain must be valid for with DANE-TA, normally the MX host name. tls is passed to Sovite.TLS.client_options/1 (:min_version, :ciphers).

matches?(cert, arg)

Returns whether the DER certificate cert matches record.

usable(records)

Keeps the records usable for SMTP: DANE-TA and DANE-EE, with a known selector and matching type, and data of the right length. If none is left, DANE does not apply and the client falls back to opportunistic TLS (RFC 7672 §2.2).

Types

tlsa()

@type tlsa() ::
  {usage :: byte(), selector :: byte(), matching_type :: byte(),
   data :: binary()}

Functions

client_options(records, hostname, tls \\ [])

@spec client_options([tlsa(), ...], String.t(), keyword()) :: [
  :ssl.tls_client_option()
]

matches?(cert, arg)

@spec matches?(binary(), tlsa()) :: boolean()

Returns whether the DER certificate cert matches record.

usable(records)

@spec usable([tlsa()]) :: [tlsa()]