preload

Documentation

Overview

Package preload implements parsing, updating and lookups for EFF STARTTLS Everywhere preload list. It can be used to prime MTA-STS cache with useful data to decrease the chance of downgrade attacks being possible.

Index

• Variables
• type Entry
  • func (e *Entry) STS(l *List) mtasts.Policy
• type List
  • func Download(h *http.Client, s Source) (*List, error)
  • func Read(r io.Reader) (*List, error)
  • func (l *List) Expired() bool
  • func (l *List) Lookup(domain string) (e Entry, ok bool)
• type ListTime
  • func (t *ListTime) MarshalJSON() ([]byte, error)
  • func (t ListTime) String() string
  • func (t *ListTime) UnmarshalJSON(b []byte) error
• type PGPError
  • func (err PGPError) Error() string
  • func (err PGPError) Unwrap() error
• type PreloadedCache
  • func WrapCache(c mtasts.Store, l *List) *PreloadedCache
  • func (pc *PreloadedCache) List() ([]string, error)
  • func (pc *PreloadedCache) Load(key string) (string, time.Time, *mtasts.Policy, error)
  • func (pc *PreloadedCache) Store(key string, id string, fetchTime time.Time, policy *mtasts.Policy) error
  • func (pc *PreloadedCache) Update(newList *List) error
• type Source

Variables

var STARTTLSEverywhere = Source{
	ListURI: "https://dl.eff.org/starttls-everywhere/policy.json",
	SigURI:  "https://dl.eff.org/starttls-everywhere/policy.json.asc",

	SigKey: `-----BEGIN PGP PUBLIC KEY BLOCK-----

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
S/SBhVRBN8L4SJ3ywKB86jnDalI=
=InKu
-----END PGP PUBLIC KEY BLOCK-----`,
}

EFF-maintained STARTTLS Everywhere preload list. https://starttls-everywhere.org/

Types

type Entry

type Entry struct {
	// Set to the normalized domain name by Lookup.
	Domain string `json:"-"`

	PolicyAlias string      `json:"policy-alias"`
	Mode        mtasts.Mode `json:"mode"`
	MXs         []string    `json:"mxs"`
}

func (*Entry) STS

func (e *Entry) STS(l *List) mtasts.Policy

STS converts the Entry into the equivalent MTA-STS policy.

type List

type List struct {
	Timestamp     ListTime         `json:"timestamp"`
	Author        string           `json:"author"`
	Version       string           `json:"version"`
	Expires       ListTime         `json:"expires"`
	PolicyAliases map[string]Entry `json:"policy-aliases"`
	Policies      map[string]Entry `json:"policies"`
}

func Download

func Download(h *http.Client, s Source) (*List, error)

Download downloads the list and verifies the PGP signature for it using source URIs provided in the Source structure.

SigURI can be set to an empty string to disable PGP verification.

func Read

func Read(r io.Reader) (*List, error)

func (*List) Expired

func (l *List) Expired() bool

Expired reports whether the list is expired and should be updated.

func (*List) Lookup

func (l *List) Lookup(domain string) (e Entry, ok bool)

Lookup extracts the corresponding entry from the list.

Ths specified domain is case-folded and converted to A-labels form before lookup.

PolicyAlias field is always empty, Lookup resolves aliases. If there is no such alias - ok = false is returned without an entry.

type ListTime

type ListTime time.Time

func (*ListTime) MarshalJSON

func (t *ListTime) MarshalJSON() ([]byte, error)

func (ListTime) String

func (t ListTime) String() string

func (*ListTime) UnmarshalJSON

func (t *ListTime) UnmarshalJSON(b []byte) error

type PGPError

type PGPError struct {
	Err error
}

PGPError is returned when Download fails due to the problem with PGP signature verification.

func (PGPError) Error

func (err PGPError) Error() string

func (PGPError) Unwrap

func (err PGPError) Unwrap() error

type PreloadedCache

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

func WrapCache

func WrapCache(c mtasts.Store, l *List) *PreloadedCache

WrapCache wraps the mtasts.Store to use the preload list as a second source to fetch policies from.

func (*PreloadedCache) List

func (pc *PreloadedCache) List() ([]string, error)

func (*PreloadedCache) Load

func (pc *PreloadedCache) Load(key string) (string, time.Time, *mtasts.Policy, error)

func (*PreloadedCache) Store

func (pc *PreloadedCache) Store(key string, id string, fetchTime time.Time, policy *mtasts.Policy) error

func (*PreloadedCache) Update

func (pc *PreloadedCache) Update(newList *List) error

Update replaces the List object used by PreloadedCache in the goroutine-safe way.

Additionally, it implements downgrade protection by returning an error when the current list is newer than newList or when the newList is already expired.

type Source

type Source struct {
	// HTTP(S) URI of the list blob.
	ListURI string

	// HTTP(S) URI of the ASCII-armored PGP signature taht is valid for data fetched
	// from ListURI.
	SigURI string

	// ASCII-armored PGP key to use when verifying the signature fetched from
	// SigURI.
	SigKey string
}