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 ¶
Constants ¶
This section is empty.
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.
Functions ¶
This section is empty.
Types ¶
type DNSResolver ¶ added in v1.2.0
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 ¶ added in v1.2.0
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 ¶ added in v1.2.0
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 ¶ added in v1.4.0
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 ¶ added in v1.2.0
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 ¶ added in v1.2.0
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 ¶ added in v1.3.0
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
deprecated
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 ¶
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.
Source Files
Directories