dkim

README

Documentation

Overview

Package dkim is a pure Go DKIM verification library.

The main use-case for the dkim package is verifying DKIM "ownership proofs" of e-mail addresses. The owner of an e-mail address can sent DKIM-signed e-mails, and anyone in the world can verify that those e-mail were sent by the owner by checking the DKIM signature. The dkim package exposes an API to verify DKIM signatures, and to inspect the signed headers of the e-mail.

As an added feature, the dkim package supports extracting and verifying just the signed headers of an e-mail. This makes ownership proofs much shorter.

Index

• type DNSClient
• type Signature
• type VerificationMode
• type VerifiedEmail
  • func ParseAndVerify(mail string, mode VerificationMode, dnsClient DNSClient) (veml *VerifiedEmail, err error)
  • func (v *VerifiedEmail) CanonHeaders() string
  • func (v *VerifiedEmail) ExtractHeader(name string) []string

Types

type DNSClient

type DNSClient interface {
	LookupTxt(hostname string) ([]string, error)
}

A DNSClient can look up TXT records.

type Signature

type Signature struct {
	// Signing domain
	Domain string
	// contains filtered or unexported fields
}

Signature describes a DKIM signature header

type VerificationMode

type VerificationMode int

VerificationMode configures the DKIM verification algorithm.

const (
	// Complete indicates that both headers and body should be verified.
	Complete VerificationMode = iota
	// HeadersOnly indicates that only headers should be verified.
	HeadersOnly
)

type VerifiedEmail

type VerifiedEmail struct {
	// Information on signature
	Signature *Signature

	// Signed headers (in original form)
	Headers []string
	// contains filtered or unexported fields
}

VerifiedEmail stores the verified parts of an e-mail.

func ParseAndVerify

func ParseAndVerify(mail string, mode VerificationMode, dnsClient DNSClient) (veml *VerifiedEmail, err error)

ParseAndVerify parses the e-mail, searches for a DKIM signature, verifies the signature, and returns the resulting verified e-mail. Results in an error if there is no valid signature.

func (*VerifiedEmail) CanonHeaders

func (v *VerifiedEmail) CanonHeaders() string

CanonHeaders computes the canonical form of the underlying e-mail in headers-only format. The result is a valid DKIM headers-only e-mail.

func (*VerifiedEmail) ExtractHeader

func (v *VerifiedEmail) ExtractHeader(name string) []string

ExtractHeader retrieves the named header from the signed headers. Returns an array of headers since headers can appear multiple times.