mtasts

README

go-mtasts

MTA-STS policy processing library for Go. Extracted from maddy code base.

See example_test.go for usage example.

Related standards

• SMTP MTA Strict Transport Security (MTA-STS) RFC 8461

Notes

• Absence of direct "download policy" and similar methods is intentional. Caching is critical for MTA-STS security.

Documentation

Overview

The mtasts policy implements parsing, caching and checking of MTA-STS (RFC 8461) policies.

Index

• Variables
• func IsNoPolicy(err error) bool
• type Cache
  • func NewFSCache(directory string) *Cache
  • func NewNopCache() *Cache
  • func NewRAMCache() *Cache
  • func (c *Cache) Get(ctx context.Context, domain string) (*Policy, error)
  • func (c *Cache) Refresh() error
• type MalformedDNSRecordError
  • func (e MalformedDNSRecordError) Error() string
• type MalformedPolicyError
  • func (e MalformedPolicyError) Error() string
• type Mode
• type Policy
  • func (p Policy) Match(mx string) bool
• type Resolver
• type Store

Examples

• Cache.Get

Variables

var ErrNoPolicy = errors.New("mtasts: no policy")

ErrNoPolicy indicates that remote domain does not offer a MTA-STS policy or it was ignored due to errors.

Callers should not check for this directly and use IsNoPolicy function to decide actual handling strategy.

Functions

func IsNoPolicy

func IsNoPolicy(err error) bool

Types

type Cache

type Cache struct {
	Store    Store
	Resolver Resolver

	// If non-nil replaces the function used to download policy texts.
	DownloadPolicy func(domain string) (*Policy, error)
}

Cache structure implements transparent MTA-STS policy caching using provided Store implementation.

It is the only way to fetch policies as caching is important to prevent downgrade attacks.

goroutine-safety is solely defined by safety of the underlying Store and Resolver objects.

func NewFSCache

func NewFSCache(directory string) *Cache

NewFSCache creates the Cache object using FS directory to store cached policies.

The specified directory should exist and be writtable.

func NewNopCache

func NewNopCache() *Cache

NewNopCache creates the Cache object that never stores fetched policies and always repeats the lookup.

It should be used only for tests, caching is criticial for the MTA-STS security model.

func NewRAMCache

func NewRAMCache() *Cache

NewRAMCache creates the Cache object using RAM map to store cached policies.

The underlying Store implementation is goroutine-safe.

func (*Cache) Get

func (c *Cache) Get(ctx context.Context, domain string) (*Policy, error)

Get reads policy from cache or tries to fetch it from Policy Host.

The domain is assumed to be normalized, as done by dns.ForLookup.

Example

c := mtasts.NewRAMCache()
policy, err := c.Get(context.Background(), "gmail.com")
if err != nil {
	fmt.Println("Oh noes!", err)
	return
}

fmt.Println("Allowed MXs:", policy.MX)

func (*Cache) Refresh

func (c *Cache) Refresh() error

type MalformedDNSRecordError

type MalformedDNSRecordError struct {
	// Additional description of the error.
	Desc string
}

func (MalformedDNSRecordError) Error

func (e MalformedDNSRecordError) Error() string

type MalformedPolicyError

type MalformedPolicyError struct {
	// Additional description of the error.
	Desc string
}

func (MalformedPolicyError) Error

func (e MalformedPolicyError) Error() string

type Mode

type Mode string

const (
	ModeEnforce Mode = "enforce"
	ModeTesting Mode = "testing"
	ModeNone    Mode = "none"
)

type Policy

type Policy struct {
	Mode   Mode
	MaxAge int
	MX     []string
}

func (Policy) Match

func (p Policy) Match(mx string) bool

type Resolver

type Resolver interface {
	LookupTXT(ctx context.Context, domain string) ([]string, error)
}

type Store

type Store interface {
	// List method is used by Cache.Refresh to clean policy data.
	List() ([]string, error)

	// Store method is used by Cache to store policy data.
	Store(key string, id string, fetchTime time.Time, policy *Policy) error

	// Load method is used by Cache to load policy data previously stored
	// using Store.
	//
	// If there is no cached policy, Load should return ErrNoPolicy.
	Load(key string) (id string, fetchTime time.Time, policy *Policy, err error)
}