mtastsdb

Documentation

Overview

Package mtastsdb stores MTA-STS policies for later use.

An MTA-STS policy can specify how long it may be cached. By storing a policy, it does not have to be fetched again during email delivery, which makes it harder for attackers to intervene.

Index

• Variables
• func Close()
• func Get(ctx context.Context, resolver dns.Resolver, domain dns.Domain) (policy *mtasts.Policy, fresh bool, err error)
• func Init(refresher bool) error
• func Upsert(domain dns.Domain, recordID string, policy *mtasts.Policy) error
• type PolicyRecord
  • func PolicyRecords(ctx context.Context) ([]PolicyRecord, error)

Variables

var (
	// No valid non-expired policy in database.
	ErrNotFound = errors.New("mtastsdb: policy not found")

	// Indicates an MTA-STS TXT record was fetched recently, but fetching the policy
	// failed and should not yet be retried.
	ErrBackoff = errors.New("mtastsdb: policy fetch failed recently")
)

Functions

func Close

func Close()

Close closes the database.

func Get

func Get(ctx context.Context, resolver dns.Resolver, domain dns.Domain) (policy *mtasts.Policy, fresh bool, err error)

Get retrieves an MTA-STS policy for domain and whether it is fresh.

If an error is returned, it should be considered a transient error, e.g. a temporary DNS lookup failure.

The returned policy can be nil also when there is no error. In this case, the domain does not implement MTA-STS.

If a policy is present in the local database, it is refreshed if needed. If no policy is present for the domain, an attempt is made to fetch the policy and store it in the local database.

Some errors are logged but not otherwise returned, e.g. if a new policy is supposedly published but could not be retrieved.

func Init

func Init(refresher bool) error

Init opens the database and starts a goroutine that refreshes policies in the database, and keeps doing so periodically.

func Upsert

func Upsert(domain dns.Domain, recordID string, policy *mtasts.Policy) error

Upsert adds the policy to the database, overwriting an existing policy for the domain. Policy can be nil, indicating a failure to fetch the policy.

Types

type PolicyRecord

type PolicyRecord struct {
	Domain        string    // Domain name, with unicode characters.
	Inserted      time.Time `bstore:"default now"`
	ValidEnd      time.Time
	LastUpdate    time.Time // Policies are refreshed on use and periodically.
	LastUse       time.Time `bstore:"index"`
	Backoff       bool
	RecordID      string // As retrieved from DNS.
	mtasts.Policy        // As retrieved from the well-known HTTPS url.
}

PolicyRecord is a cached policy or absence of a policy.

func PolicyRecords

func PolicyRecords(ctx context.Context) ([]PolicyRecord, error)

PolicyRecords returns all policies in the database, sorted descending by last use, domain.