spf

README

blitiri.com.ar/go/spf

spf is an open source implementation of the Sender Policy Framework (SPF) in Go.

It is used by the chasquid and maddy SMTP servers.

Example

// Check if `sender` is authorized to send from the given `ip`. The `domain`
// is used if the sender doesn't have one.
result, err := spf.CheckHostWithSender(ip, domain, sender)
if result == spf.Fail {
	// Not authorized to send.
}

See the package documentation for more details.

Status

All SPF mechanisms, modifiers, and macros are supported.

The API should be considered stable. Major version changes will be announced to the mailing list (details below).

Contact

If you have any questions, comments or patches please send them to the mailing list, chasquid@googlegroups.com.

To subscribe, send an email to chasquid+subscribe@googlegroups.com.

You can also browse the archives.

Documentation

Overview

Package spf implements SPF (Sender Policy Framework) lookup and validation.

Sender Policy Framework (SPF) is a simple email-validation system designed to detect email spoofing by providing a mechanism to allow receiving mail exchangers to check that incoming mail from a domain comes from a host authorized by that domain's administrators [Wikipedia].

This package is intended to be used by SMTP servers to implement SPF validation.

All mechanisms and modifiers are supported:

all
include
a
mx
ptr
ip4
ip6
exists
redirect
exp (ignored)
Macros

References:

https://tools.ietf.org/html/rfc7208
https://en.wikipedia.org/wiki/Sender_Policy_Framework

Index

• Variables
• type DNSResolver
• type Option
  • func OverrideLookupLimit(limit uint) Option
  • func OverrideVoidLookupLimit(limit uint) Option
  • func WithContext(ctx context.Context) Option
  • func WithResolver(resolver DNSResolver) Option
  • func WithTraceFunc(trace TraceFunc) Option
• type Result
  • func CheckHost(ip net.IP, domain string) (Result, error)
  • func CheckHostWithSender(ip net.IP, helo, sender string, opts ...Option) (Result, error)
• type TraceFunc

Variables

var (
	// https://tools.ietf.org/html/rfc7208#section-8.1
	// Not able to reach any conclusion.
	None = Result("none")

	// https://tools.ietf.org/html/rfc7208#section-8.2
	// No definite assertion (positive or negative).
	Neutral = Result("neutral")

	// https://tools.ietf.org/html/rfc7208#section-8.3
	// Client is authorized to inject mail.
	Pass = Result("pass")

	// https://tools.ietf.org/html/rfc7208#section-8.4
	// Client is *not* authorized to use the domain.
	Fail = Result("fail")

	// https://tools.ietf.org/html/rfc7208#section-8.5
	// Not authorized, but unwilling to make a strong policy statement.
	SoftFail = Result("softfail")

	// https://tools.ietf.org/html/rfc7208#section-8.6
	// Transient error while performing the check.
	TempError = Result("temperror")

	// https://tools.ietf.org/html/rfc7208#section-8.7
	// Records could not be correctly interpreted.
	PermError = Result("permerror")
)

Valid results.

var (
	// Errors related to an invalid SPF record.
	ErrUnknownField  = errors.New("unknown field")
	ErrInvalidIP     = errors.New("invalid ipX value")
	ErrInvalidMask   = errors.New("invalid mask")
	ErrInvalidMacro  = errors.New("invalid macro")
	ErrInvalidDomain = errors.New("invalid domain")

	// Errors related to DNS lookups.
	// Note that the library functions may also return net.DNSError.
	ErrNoResult               = errors.New("no DNS record found")
	ErrLookupLimitReached     = errors.New("lookup limit reached")
	ErrVoidLookupLimitReached = errors.New("void lookup limit reached")
	ErrTooManyMXRecords       = errors.New("too many MX records")
	ErrMultipleRecords        = errors.New("multiple matching DNS records")

	// Errors returned on a successful match.
	ErrMatchedAll    = errors.New("matched all")
	ErrMatchedA      = errors.New("matched a")
	ErrMatchedIP     = errors.New("matched ip")
	ErrMatchedMX     = errors.New("matched mx")
	ErrMatchedPTR    = errors.New("matched ptr")
	ErrMatchedExists = errors.New("matched exists")
)

Errors returned by the library. Note that the errors returned in different situations may change over time, and new ones may be added. Be careful about over-relying on these.

Types

type DNSResolver

type DNSResolver interface {
	LookupTXT(ctx context.Context, name string) ([]string, error)
	LookupMX(ctx context.Context, name string) ([]*net.MX, error)
	LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)
	LookupAddr(ctx context.Context, addr string) (names []string, err error)
}

DNSResolver implements the methods we use to resolve DNS queries. It is intentionally compatible with *net.Resolver.

type Option

type Option func(*resolution)

Option type, for setting options. Users are expected to treat this as an opaque type and not rely on the implementation, which is subject to change.

func OverrideLookupLimit

func OverrideLookupLimit(limit uint) Option

OverrideLookupLimit overrides the maximum number of DNS lookups allowed during SPF evaluation. Note that using this violates the RFC, which is quite explicit that the maximum allowed MUST be 10 (the default). Please use with care.

This is EXPERIMENTAL for now, and the API is subject to change.

func OverrideVoidLookupLimit

func OverrideVoidLookupLimit(limit uint) Option

OverrideVoidLookupLimit overrides the maximum number of void DNS lookups allowed during SPF evaluation. A void DNS lookup is one that returns an empty answer, or a NXDOMAIN. Note that as per RFC, the default value of 2 SHOULD be used. Please use with care.

This is EXPERIMENTAL for now, and the API is subject to change.

func WithContext

func WithContext(ctx context.Context) Option

WithContext is an option to set the context for this operation, which will be passed along to the resolver functions and other external calls if needed.

This is EXPERIMENTAL for now, and the API is subject to change.

func WithResolver

func WithResolver(resolver DNSResolver) Option

WithResolver sets the resolver to use for DNS lookups. It can be useful for testing, and for customize DNS resolution specifically for this library.

The default is to use net.DefaultResolver, which should be appropriate for most users.

This is EXPERIMENTAL for now, and the API is subject to change.

func WithTraceFunc

func WithTraceFunc(trace TraceFunc) Option

WithTraceFunc sets the resolver's trace function.

This can be used for debugging. The trace messages are NOT machine parseable, and are NOT stable. They should also NOT be included in user-visible output, as they may include sensitive details.

This is EXPERIMENTAL for now, and the API is subject to change.

type Result

type Result string

The Result of an SPF check. Note the values have meaning, we use them in headers. https://tools.ietf.org/html/rfc7208#section-8

func CheckHost

func CheckHost(ip net.IP, domain string) (Result, error)

CheckHost fetches SPF records for `domain`, parses them, and evaluates them to determine if `ip` is permitted to send mail for it. Because it doesn't receive enough information to handle macros well, its usage is not recommended, but remains supported for backwards compatibility.

The function returns a Result, which corresponds with the SPF result for the check as per RFC, as well as an error for debugging purposes. Note that the error may be non-nil even on successful checks.

Reference: https://tools.ietf.org/html/rfc7208#section-4

Deprecated: use CheckHostWithSender instead.

func CheckHostWithSender

func CheckHostWithSender(ip net.IP, helo, sender string, opts ...Option) (Result, error)

CheckHostWithSender fetches SPF records for `sender`'s domain, parses them, and evaluates them to determine if `ip` is permitted to send mail for it. The `helo` domain is used if the sender has no domain part.

The `opts` optional parameter can be used to adjust some specific behaviours, such as the maximum number of DNS lookups allowed.

The function returns a Result, which corresponds with the SPF result for the check as per RFC, as well as an error for debugging purposes. Note that the error may be non-nil even on successful checks.

Reference: https://tools.ietf.org/html/rfc7208#section-4

type TraceFunc

type TraceFunc func(f string, a ...interface{})

TraceFunc is the type of tracing functions.