sts

Documentation

Overview

Package sts implements the MTA-STS (Strict Transport Security), RFC 8461.

Note that "report" mode is not supported.

Reference: https://tools.ietf.org/html/rfc8461

Index

• Constants
• Variables
• type Mode
• type Policy
  • func Fetch(ctx context.Context, domain string) (*Policy, error)
  • func UncheckedFetch(ctx context.Context, domain string) (*Policy, error)
  • func (p *Policy) Check() error
  • func (p *Policy) MXIsAllowed(mx string) bool
• type PolicyCache
  • func NewCache(dir string) (*PolicyCache, error)
  • func (c *PolicyCache) Fetch(ctx context.Context, domain string) (*Policy, error)
  • func (c *PolicyCache) PeriodicallyRefresh(ctx context.Context)

Constants

const (
	Enforce = Mode("enforce")
	Testing = Mode("testing")
	None    = Mode("none")
)

Valid modes.

Variables

var (
	ErrUnknownVersion = errors.New("unknown policy version")
	ErrInvalidMaxAge  = errors.New("invalid max_age")
	ErrInvalidMode    = errors.New("invalid mode")
	ErrInvalidMX      = errors.New("invalid mx")
)

Check errors.

var (
	ErrInvalidMediaType = errors.New("invalid HTTP media type")
)

Fetch errors.

Types

type Mode

type Mode string

The Mode of a policy. Valid values (according to the standard) are constants below.

type Policy

type Policy struct {
	Version string        `json:"version"`
	Mode    Mode          `json:"mode"`
	MXs     []string      `json:"mx"`
	MaxAge  time.Duration `json:"max_age"`
}

Policy represents a parsed policy. https://tools.ietf.org/html/rfc8461#section-3.2 The json annotations are used for serializing for caching purposes.

func Fetch

func Fetch(ctx context.Context, domain string) (*Policy, error)

Fetch a policy for the given domain. Note this results in various network lookups and HTTPS GETs, so it can be slow. The returned policy is parsed and sanity-checked (using Policy.Check), so it should be safe to use.

func UncheckedFetch

func UncheckedFetch(ctx context.Context, domain string) (*Policy, error)

UncheckedFetch fetches and parses the policy, but does NOT check it. This can be useful for debugging and troubleshooting, but you should always call Check on the policy before using it.

func (*Policy) Check

func (p *Policy) Check() error

Check that the policy contents are valid.

func (*Policy) MXIsAllowed

func (p *Policy) MXIsAllowed(mx string) bool

MXIsAllowed checks if the given MX is allowed, according to the policy. https://tools.ietf.org/html/rfc8461#section-4.1

type PolicyCache

type PolicyCache struct {
	// contains filtered or unexported fields
}

PolicyCache is a caching layer for fetching policies.

Policies are cached by domain, and stored in a single directory. The files will have as mtime the time when the policy expires, this makes the store simpler, as it can avoid keeping additional metadata.

There is no in-memory caching. This may be added in the future, but for now disk is good enough for our purposes.

func NewCache

func NewCache(dir string) (*PolicyCache, error)

NewCache creates an instance of PolicyCache using the given directory as backing storage. The directory will be created if it does not exist.

func (*PolicyCache) Fetch

func (c *PolicyCache) Fetch(ctx context.Context, domain string) (*Policy, error)

Fetch a policy for the given domain, using the cache.

func (*PolicyCache) PeriodicallyRefresh

func (c *PolicyCache) PeriodicallyRefresh(ctx context.Context)

PeriodicallyRefresh the cache, by re-fetching all entries.