tlsrpt

Documentation

Overview

Package tlsrpt implements SMTP TLS Reporting, RFC 8460.

TLSRPT allows a domain to publish a policy requesting feedback of TLS connectivity to its SMTP servers. Reports can be sent to an address defined in the TLSRPT DNS record. These reports can be parsed by tlsrpt.

Index

• Variables
• type Extension
• type FailureDetails
• type Record
  • func Lookup(ctx context.Context, resolver dns.Resolver, domain dns.Domain) (rrecord *Record, rtxt string, rerr error)
  • func ParseRecord(txt string) (record *Record, istlsrpt bool, err error)
  • func (r Record) String() string
• type Report
  • func Parse(r io.Reader) (*Report, error)
  • func ParseMessage(r io.ReaderAt) (*Report, error)
• type Result
• type ResultPolicy
• type ResultType
• type Summary
• type TLSRPTDateRange
  • func (dr *TLSRPTDateRange) UnmarshalJSON(buf []byte) error

Variables

var (
	ErrNoRecord        = errors.New("tlsrpt: no tlsrpt dns txt record")
	ErrMultipleRecords = errors.New("tlsrpt: multiple tlsrpt records") // Must be treated as if domain does not implement TLSRPT.
	ErrDNS             = errors.New("tlsrpt: temporary error")
	ErrRecordSyntax    = errors.New("tlsrpt: record syntax error")
)

var ErrNoReport = errors.New("no tlsrpt report found")

Types

type Extension

type Extension struct {
	Key   string
	Value string
}

Extension is an additional key/value pair for a TLSRPT record.

type FailureDetails

type FailureDetails struct {
	ResultType            ResultType `json:"result-type"`
	SendingMTAIP          string     `json:"sending-mta-ip"`
	ReceivingMXHostname   string     `json:"receiving-mx-hostname"`
	ReceivingMXHelo       string     `json:"receiving-mx-helo"`
	ReceivingIP           string     `json:"receiving-ip"`
	FailedSessionCount    int64      `json:"failed-session-count"`
	AdditionalInformation string     `json:"additional-information"`
	FailureReasonCode     string     `json:"failure-reason-code"`
}

type Record

type Record struct {
	Version    string     // "TLSRPTv1", for "v=".
	RUAs       [][]string // Aggregate reporting URI, for "rua=". "rua=" can occur multiple times, each can be a list. Must be URL-encoded strings, with ",", "!" and ";" encoded.
	Extensions []Extension
}

Record is a parsed TLSRPT record, to be served under "_smtp._tls.<domain>".

Example:

v=TLSRPTv1; rua=mailto:tlsrpt@mox.example;

func Lookup

func Lookup(ctx context.Context, resolver dns.Resolver, domain dns.Domain) (rrecord *Record, rtxt string, rerr error)

Lookup looks up a TLSRPT DNS TXT record for domain at "_smtp._tls.<domain>" and parses it.

func ParseRecord

func ParseRecord(txt string) (record *Record, istlsrpt bool, err error)

ParseRecord parses a TLSRPT record.

func (Record) String

func (r Record) String() string

String returns a string or use as a TLSRPT DNS TXT record.

type Report

type Report struct {
	OrganizationName string          `json:"organization-name"`
	DateRange        TLSRPTDateRange `json:"date-range"`
	ContactInfo      string          `json:"contact-info"` // Email address.
	ReportID         string          `json:"report-id"`
	Policies         []Result        `json:"policies"`
}

Report is a TLSRPT report, transmitted in JSON format.

func Parse

func Parse(r io.Reader) (*Report, error)

Parse parses a Report. The maximum size is 20MB.

func ParseMessage

func ParseMessage(r io.ReaderAt) (*Report, error)

ParseMessage parses a Report from a mail message. The maximum size of the message is 15MB, the maximum size of the decompressed report is 20MB.

type Result

type Result struct {
	Policy         ResultPolicy     `json:"policy"`
	Summary        Summary          `json:"summary"`
	FailureDetails []FailureDetails `json:"failure-details"`
}

type ResultPolicy

type ResultPolicy struct {
	Type   string   `json:"policy-type"`
	String []string `json:"policy-string"`
	Domain string   `json:"policy-domain"`
	MXHost []string `json:"mx-host"` // Example in RFC has errata, it originally was a single string. ../rfc/8460-eid6241 ../rfc/8460:1779
}

type ResultType

type ResultType string

ResultType represents a TLS error.

const (
	ResultSTARTTLSNotSupported    ResultType = "starttls-not-supported"
	ResultCertificateHostMismatch ResultType = "certificate-host-mismatch"
	ResultCertificateExpired      ResultType = "certificate-expired"
	ResultTLSAInvalid             ResultType = "tlsa-invalid"
	ResultDNSSECInvalid           ResultType = "dnssec-invalid"
	ResultDANERequired            ResultType = "dane-required"
	ResultCertificateNotTrusted   ResultType = "certificate-not-trusted"
	ResultSTSPolicyInvalid        ResultType = "sts-policy-invalid"
	ResultSTSWebPKIInvalid        ResultType = "sts-webpki-invalid"
	ResultValidationFailure       ResultType = "validation-failure" // Other error.
	ResultSTSPolicyFetch          ResultType = "sts-policy-fetch-error"
)

type Summary

type Summary struct {
	TotalSuccessfulSessionCount int64 `json:"total-successful-session-count"`
	TotalFailureSessionCount    int64 `json:"total-failure-session-count"`
}

type TLSRPTDateRange

type TLSRPTDateRange struct {
	Start time.Time `json:"start-datetime"`
	End   time.Time `json:"end-datetime"`
}

note: with TLSRPT prefix to prevent clash in sherpadoc types.

func (*TLSRPTDateRange) UnmarshalJSON

func (dr *TLSRPTDateRange) UnmarshalJSON(buf []byte) error

UnmarshalJSON is defined on the date range, not the individual time.Time fields because it is easier to keep the unmodified time.Time fields stored in the database.