dkim

README

go-dkim

DKIM package for Golang

Getting started

Install

 	go get github.com/toorop/go-dkim

Warning: you need to use Go 1.4.2-master or 1.4.3 (when it will be available) see https://github.com/golang/go/issues/10482 fro more info.

Sign email

import (
	dkim "github.com/toorop/go-dkim"
)

func main(){
	// email is the email to sign (byte slice)
	// privateKey the private key (pem encoded, byte slice )	
	options := dkim.NewSigOptions()
	options.PrivateKey = privateKey
	options.Domain = "mydomain.tld"
	options.Selector = "myselector"
	options.SignatureExpireIn = 3600
	options.BodyLength = 50
	options.Headers = []string{"from", "date", "mime-version", "received", "received"}
	options.AddSignatureTimestamp = true
	options.Canonicalization = "relaxed/relaxed"
	err := dkim.Sign(&email, options)
	// handle err..

	// And... that's it, 'email' is signed ! Amazing© !!!
}

Verify

import (
	dkim "github.com/toorop/go-dkim"
)

func main(){
	// email is the email to verify (byte slice)
	status, err := Verify(&email)
	// handle status, err (see godoc for status)
}

Todo

• handle z tag (copied header fields used for diagnostic use)

Documentation

Overview

Package dkim provides tools for signing and verify a email according to RFC 6376

Index

• Constants
• Variables
• func NewPubKeyFromDnsTxt(txt string) (*pubKeyRep, verifyOutput, error)
• func Sign(email *[]byte, options SigOptions) error
• func Verify(email *[]byte) (verifyOutput, error)
• type SigOptions
  • func NewSigOptions() SigOptions

Constants

const (
	CRLF                = "\r\n"
	TAB                 = " "
	FWS                 = CRLF + TAB
	MaxHeaderLineLength = 70
)

const (
	SUCCESS verifyOutput = 1 + iota
	PERMFAIL
	TEMPFAIL
	NOTSIGNED
	TESTINGSUCCESS
	TESTINGPERMFAIL
	TESTINGTEMPFAIL
)

Variables

var (
	// ErrSignPrivateKeyRequired when there not private key in config
	ErrSignPrivateKeyRequired = errors.New("PrivateKey is required")

	// ErrSignDomainRequired when there is no domain defined in config
	ErrSignDomainRequired = errors.New("Domain is required")

	// ErrSignSelectorRequired when there is no Selcteir defined in config
	ErrSignSelectorRequired = errors.New("Selector is required")

	// ErrSignHeaderShouldContainsFrom If Headers is specified it should at least contain 'from'
	ErrSignHeaderShouldContainsFrom = errors.New("header must contains 'from' field")

	// ErrSignBadCanonicalization If bad Canonicalization parameter
	ErrSignBadCanonicalization = errors.New("bad Canonicalization parameter")

	// ErrCandNotParsePrivateKey when unable to parse private key
	ErrCandNotParsePrivateKey = errors.New("can not parse private key, check format (pem) and validity")

	// ErrSignBadAlgo Bad algorithm
	ErrSignBadAlgo = errors.New("bad algorithm. Only rsa-sha1 or rsa-sha256 are permitted")

	// ErrBadMailFormat unable to parse mail
	ErrBadMailFormat = errors.New("bad mail format")

	// ErrBadMailFormatHeaders bad headers format (not DKIM Header)
	ErrBadMailFormatHeaders = errors.New("bad mail format found in headers")

	// ErrBadDKimTagLBodyTooShort bad l tag
	ErrBadDKimTagLBodyTooShort = errors.New("bad tag l or bodyLength option. Body length < l value")

	// ErrDkimHeaderBadFormat when errors found in DKIM header
	ErrDkimHeaderBadFormat = errors.New("bad DKIM header format")

	// ErrDkimHeaderNotFound when there's no DKIM-Signature header in an email we have to verify
	ErrDkimHeaderNotFound = errors.New("no DKIM-Signature header field found ")

	// ErrDkimHeaderBTagNotFound when there's no b tag
	ErrDkimHeaderBTagNotFound = errors.New("no tag 'b' found in dkim header")

	// ErrDkimHeaderNoFromInHTag when from is missing in h tag
	ErrDkimHeaderNoFromInHTag = errors.New("'from' header is missing in h tag")

	// ErrDkimHeaderMissingRequiredTag when a required tag is missing
	ErrDkimHeaderMissingRequiredTag = errors.New("signature missing required tag")

	// ErrDkimHeaderDomainMismatch if i tag is not a sub domain of d tag
	ErrDkimHeaderDomainMismatch = errors.New("domain mismatch")

	// ErrDkimVersionNotsupported version not supported
	ErrDkimVersionNotsupported = errors.New("incompatible version")

	// ErrVerifyBodyHash when body hash doesn't verify
	ErrVerifyBodyHash = errors.New("body hash did not verify")

	// ErrVerifyNoKeyForSignature no key
	ErrVerifyNoKeyForSignature = errors.New("no key for verify")

	// ErrVerifyKeyUnavailable when service (dns) is anavailable
	ErrVerifyKeyUnavailable = errors.New("key unavailable")

	// ErrVerifyTagVMustBeTheFirst if present the v tag must be the firts in the record
	ErrVerifyTagVMustBeTheFirst = errors.New("pub key syntax error: v tag must be the first")

	// ErrVerifyVersionMusBeDkim1 if présent flag v (version) must be DKIM1
	ErrVerifyVersionMusBeDkim1 = errors.New("flag v must be set to DKIM1")

	// ErrVerifyBadKeyType bad type for pub key (only rsa is accepted)
	ErrVerifyBadKeyType = errors.New("bad type for key type")

	// ErrVerifyRevokedKey key(s) for this selector is revoked (p is empty)
	ErrVerifyRevokedKey = errors.New("revoked key")

	// ErrVerifyBadKey when we can't parse pubkey
	ErrVerifyBadKey = errors.New("unable to parse pub key")

	// ErrVerifyNoKey when no key is found on DNS record
	ErrVerifyNoKey = errors.New("no public key found in DNS TXT")

	// ErrVerifySignatureHasExpired when signature has expired
	ErrVerifySignatureHasExpired = errors.New("signature has expired")

	// ErrVerifyInappropriateHashAlgo when h tag in pub key doesn't contain hash algo from a tag of DKIM header
	ErrVerifyInappropriateHashAlgo = errors.New("inappropriate has algorithm")
)

Functions

func NewPubKeyFromDnsTxt

func NewPubKeyFromDnsTxt(txt string) (*pubKeyRep, verifyOutput, error)

func Sign

func Sign(email *[]byte, options SigOptions) error

Sign signs an email

func Verify

func Verify(email *[]byte) (verifyOutput, error)

Verify verifies an email an return state: SUCCESS or PERMFAIL or TEMPFAIL, TESTINGSUCCESS, TESTINGPERMFAIL TESTINGTEMPFAIL or NOTSIGNED error: if an error occurs during verification

Types

type SigOptions

type SigOptions struct {

	// DKIM version (default 1)
	Version uint

	// Private key used for signing (required)
	PrivateKey []byte

	// Domain (required)
	Domain string

	// Selector (required)
	Selector string

	// The Agent of User IDentifier
	Auid string

	// Message canonicalization (plain-text; OPTIONAL, default is
	// "simple/simple").  This tag informs the Verifier of the type of
	// canonicalization used to prepare the message for signing.
	Canonicalization string

	// The algorithm used to generate the signature
	//"rsa-sha1" or "rsa-sha256"
	Algo string

	// Signed header fields
	Headers []string

	// Body length count( if set to 0 this tag is ommited in Dkim header)
	BodyLength uint

	// Query Methods used to retrieve the public key
	QueryMethods []string

	// Add a signature timestamp
	AddSignatureTimestamp bool

	// Time validity of the signature (0=never)
	SignatureExpireIn uint64

	// CopiedHeaderFileds
	CopiedHeaderFields []string
}

sigOptions represents signing options

func NewSigOptions

func NewSigOptions() SigOptions

NewSigOptions returns new sigoption with some defaults value