milter

README

milter

A golang library for milter support heavily inspired from https://github.com/andybalholm/milter For example how to use the library see https://github.com/phalaaxx/pf-milters - postfix milter for email classification with bogofilter and blacklisting messages which contain files with executable extensions.

Documentation

Overview

Modifier object instance is provided to milter handlers to modify email messages

Index

• Constants
• Variables
• func DecodeCStrings(data []byte) []string
• func ReadCString(data []byte) string
• func RunServer(server net.Listener, init MilterInit) error
• type CustomResponse
  • func NewResponse(code byte, data []byte) *CustomResponse
  • func NewResponseStr(code byte, data string) *CustomResponse
  • func (c *CustomResponse) Continue() bool
  • func (c *CustomResponse) Response() *Message
• type Message
• type Milter
• type MilterInit
• type MilterSession
  • func (m *MilterSession) HandleMilterCommands()
  • func (m *MilterSession) Process(msg *Message) (Response, error)
  • func (c *MilterSession) ReadPacket() (*Message, error)
  • func (m *MilterSession) WritePacket(msg *Message) error
• type Modifier
  • func NewModifier(s *MilterSession) *Modifier
  • func (m *Modifier) AddHeader(name, value string) error
  • func (m *Modifier) AddRecipient(r string) error
  • func (m *Modifier) ChangeHeader(index int, name, value string) error
  • func (m *Modifier) DeleteRecipient(r string) error
  • func (m *Modifier) Quarantine(reason string) error
  • func (m *Modifier) ReplaceBody(body []byte) error
• type Response
• type SimpleResponse
  • func (r SimpleResponse) Continue() bool
  • func (r SimpleResponse) Response() *Message

Constants

const (
	Accept   = 'a'
	Continue = 'c'
	Discard  = 'd'
	Reject   = 'r'
	TempFail = 't'
)

Define milter response codes

const (
	RespAccept   = SimpleResponse(Accept)
	RespContinue = SimpleResponse(Continue)
	RespDiscard  = SimpleResponse(Discard)
	RespReject   = SimpleResponse(Reject)
	RespTempFail = SimpleResponse(TempFail)
)

Define standard responses with no data

const (
	// negotiation actions
	OptAddHeader = 1 << iota
	OptChangeBody
	OptAddRcpt
	OptRemoveRcpt
	OptChangeHeader
	OptQuarantine
	OptChangeFrom
	OptAddRcptWithArgs
	OptSetMacroList
)

const (
	// undesired protocol content
	OptNoConnect = 1 << iota
	OptNoHelo
	OptNoMailFrom
	OptNoRcptTo
	OptNoBody
	OptNoHeaders
	OptNoEOH
	OptNoReplyToHeaders
	OptNoUnknown
	OptNoData
	OptSkipEventNextTime
	OptWithRejectedRcpt
	OptNoReplyToConnect
	OptNoReplyToHelo
	OptNoReplyToMail
	OptNoReplyToRcpt
	OptNoReplyToData
	OptNoReplyToUnkn
	OptNoReplyToEOH
	OptNoReplyToBody
	OptHeaderValuesWithLeadingSpace
)

const NULL = "\x00"

NULL terminator

Variables

var (
	ECloseSession = errors.New("Stop current milter processing")
	EMacroNoData  = errors.New("Macro definition with no data")
)

pre-defined errors

Functions

func DecodeCStrings

func DecodeCStrings(data []byte) []string

DecodeCStrings splits c style strings into golang slice

func ReadCString

func ReadCString(data []byte) string

ReadCString reads and returs c style string from []byte

func RunServer

func RunServer(server net.Listener, init MilterInit) error

RunServer provides a convinient way to start milter server

Types

type CustomResponse

type CustomResponse struct {
	Code byte
	Data []byte
}

CustomResponse is a response object used by callback handlers to indicate how the milter should continue processing of current message

func NewResponse

func NewResponse(code byte, data []byte) *CustomResponse

NewResponse generates a new CustomRespanse suitable for WritePacket

func NewResponseStr

func NewResponseStr(code byte, data string) *CustomResponse

NewResponseStr generates a new CustomResponse with string payload

func (*CustomResponse) Continue

func (c *CustomResponse) Continue() bool

Continue returns false if milter chain should be stopped, true otherwise

func (*CustomResponse) Response

func (c *CustomResponse) Response() *Message

Response returns message object with data

type Message

type Message struct {
	Code byte
	Data []byte
}

Message represents commant sent from milter client

type Milter

type Milter interface {
	// Connect is called to provide SMTP connection data for incoming message
	//   supress with NoConnect
	Connect(string, string, uint16, net.IP, *Modifier) (Response, error)

	// Helo is called to process any HELO/EHLO related filters
	//   supress with NoHelo
	Helo(string, *Modifier) (Response, error)

	// MailFrom is called to process filters on envelope FROM address
	//   supress with NoMailForm
	MailFrom(string, *Modifier) (Response, error)

	// RcptTo is called to process filters on envelope TO address
	//   supress with NoRcptTo
	RcptTo(string, *Modifier) (Response, error)

	// Header is called once for each header in incoming message
	//   supress with NoHeaders
	Header(string, string, *Modifier) (Response, error)

	// Headers is called when all message headers have been processed
	//   supress with NoHeaders
	Headers(textproto.MIMEHeader, *Modifier) (Response, error)

	// BodyChunk is called to process next message body chunk data (up to 64KB in size)
	//   supress with NoBody
	BodyChunk([]byte, *Modifier) (Response, error)

	// Body is called when entire message body has been passed to milter
	//   supress with NoBody
	Body(*Modifier) (Response, error)
}

Milter is an interface for milter callback handlers

type MilterInit

type MilterInit func() (Milter, uint32, uint32)

MilterInit is a function that initializes milter object options

type MilterSession

type MilterSession struct {
	Actions  uint32
	Protocol uint32
	Sock     io.ReadWriteCloser
	Headers  textproto.MIMEHeader
	Macros   map[string]string
	Milter   Milter
}

MilterSession is keeps session state during MTA communication

func (*MilterSession) HandleMilterCommands

func (m *MilterSession) HandleMilterCommands()

process all milter commands in the same connection

func (*MilterSession) Process

func (m *MilterSession) Process(msg *Message) (Response, error)

Process incoming milter command

func (*MilterSession) ReadPacket

func (c *MilterSession) ReadPacket() (*Message, error)

ReadPacket reads incoming milter packet

func (*MilterSession) WritePacket

func (m *MilterSession) WritePacket(msg *Message) error

WritePacket sends a milter response packet to socket stream

type Modifier

type Modifier struct {
	Macros      map[string]string
	Headers     textproto.MIMEHeader
	WritePacket func(*Message) error
}

Modifier provides access to Macros, Headers and Body data to callback handlers. It also defines a

number of functions that can be used by callback handlers to modify processing of the email message

func NewModifier

func NewModifier(s *MilterSession) *Modifier

NewModifier creates a new Modifier object from MilterSession

func (*Modifier) AddHeader

func (m *Modifier) AddHeader(name, value string) error

AddHeader appends a new email message header the message

func (*Modifier) AddRecipient

func (m *Modifier) AddRecipient(r string) error

AddRecipient appends a new envelope recipient for current message

func (*Modifier) ChangeHeader

func (m *Modifier) ChangeHeader(index int, name, value string) error

ChangeHeader replaces the header at the pecified position with a new one

func (*Modifier) DeleteRecipient

func (m *Modifier) DeleteRecipient(r string) error

DeleteRecipient removes an envelope recipient address from message

func (*Modifier) Quarantine

func (m *Modifier) Quarantine(reason string) error

Quarantine a message by giving a reason to hold it

func (*Modifier) ReplaceBody

func (m *Modifier) ReplaceBody(body []byte) error

ReplaceBody substitutes message body with provided body

type Response

type Response interface {
	Response() *Message
	Continue() bool
}

Response represents a response structure returned by callback

handlers to indicate how the milter server should proceed

type SimpleResponse

type SimpleResponse byte

SimpleResponse interface to define list of pre-defined responses

func (SimpleResponse) Continue

func (r SimpleResponse) Continue() bool

Continue to process milter messages only if current code is Continue

func (SimpleResponse) Response

func (r SimpleResponse) Response() *Message

Response returns a Message object reference