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, elog *slog.Logger, resolver dns.Resolver, ...) (policy *mtasts.Policy, reportResult tlsrpt.Result, fresh bool, err error)
• func Init(refresher bool) error
• func Upsert(ctx context.Context, 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")
)

var DB *bstore.DB // Exported for backups.

var DBTypes = []any{PolicyRecord{}} // Types stored in DB.

Functions

func Close

func Close()

Close closes the database.

func Get

func Get(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, domain dns.Domain) (policy *mtasts.Policy, reportResult tlsrpt.Result, 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.

Get returns an "sts" or "no-policy-found" in reportResult in most cases (when not a local/internal error). It may add an "sts" result without policy contents ("policy-string") in case of errors while fetching the policy.

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(ctx context.Context, domain dns.Domain, recordID string, policy *mtasts.Policy, policyText string) 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.

	// Text that make up the policy, as retrieved. We didn't store this in the past. If
	// empty, policy can be reconstructed from Policy field. Needed by TLSRPT.
	PolicyText string
}

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.