smtpd

README

This is an internal fork of github.com/chrj/smtpd, with the following initial changes:

• removed the _examples directory
• removed the go.mod file
• replaced the README.md file with this one

This internal fork will change over time to meet our needs, and may diverge from the original.

The original license is included in this directory as LICENSE.

Documentation

Overview

Package smtpd implements an SMTP server with support for STARTTLS, authentication (PLAIN/LOGIN), XCLIENT and optional restrictions on the different stages of the SMTP session.

Index

• Variables
• func LocalAddrFromContext(ctx context.Context) net.Addr
• type Envelope
  • func (env *Envelope) AddReceivedLine(peer Peer)
• type Peer
• type Protocol
• type Server
  • func (srv *Server) Address() net.Addr
  • func (srv *Server) ListenAndServe(ctx context.Context, addr string) error
  • func (srv *Server) Serve(ctx context.Context, l net.Listener) error
  • func (srv *Server) Shutdown(wait bool) error
  • func (srv *Server) Wait() error

Variables

var (
	ErrBusy              = &textproto.Error{Code: 421, Msg: "Too busy. Try again later."}
	ErrIPDenied          = &textproto.Error{Code: 421, Msg: "Denied - IP out of allowed network range"}
	ErrRecipientDenied   = &textproto.Error{Code: 451, Msg: "Denied recipient address"}
	ErrRecipientInvalid  = &textproto.Error{Code: 451, Msg: "Invalid recipient address"}
	ErrSenderDenied      = &textproto.Error{Code: 451, Msg: "sender address not allowed"}
	ErrTooManyRecipients = &textproto.Error{Code: 452, Msg: "Too many recipients"}

	ErrLineTooLong           = &textproto.Error{Code: 500, Msg: "Line too long"}
	ErrDuplicateMAIL         = &textproto.Error{Code: 502, Msg: "Duplicate MAIL"}
	ErrDuplicateSTARTTLS     = &textproto.Error{Code: 502, Msg: "Already running in TLS"}
	ErrInvalidSyntax         = &textproto.Error{Code: 502, Msg: "Invalid syntax."}
	ErrMalformedAuth         = &textproto.Error{Code: 502, Msg: "Couldn't decode your credentials"}
	ErrMalformedCommand      = &textproto.Error{Code: 502, Msg: "Couldn't decode the command"}
	ErrMalformedEmail        = &textproto.Error{Code: 502, Msg: "Malformed email address"} // TODO: should this be a 502 or 451?
	ErrMissingParam          = &textproto.Error{Code: 502, Msg: "Missing parameter"}
	ErrNoHELO                = &textproto.Error{Code: 502, Msg: "Please introduce yourself first."}
	ErrNoMAIL                = &textproto.Error{Code: 502, Msg: "Missing MAIL FROM command."}
	ErrNoRCPT                = &textproto.Error{Code: 502, Msg: "Missing RCPT TO command."}
	ErrNoSTARTTLS            = &textproto.Error{Code: 502, Msg: "Please turn on TLS by issuing a STARTTLS command."}
	ErrTLSNotSupported       = &textproto.Error{Code: 502, Msg: "TLS not supported"}
	ErrUnknownAuth           = &textproto.Error{Code: 502, Msg: "Unknown authentication mechanism"}
	ErrUnsupportedCommand    = &textproto.Error{Code: 502, Msg: "Unsupported command"}
	ErrUnsupportedConn       = &textproto.Error{Code: 502, Msg: "Unsupported network connection"}
	ErrUnsupportedAuthMethod = &textproto.Error{Code: 530, Msg: "Authentication method not supported"}
	ErrAuthRequired          = &textproto.Error{Code: 530, Msg: "Authentication required."}
	ErrAuthInvalid           = &textproto.Error{Code: 535, Msg: "Authentication credentials invalid"}
	ErrBadHandshake          = &textproto.Error{Code: 550, Msg: "Handshake error"}
	ErrTooBig                = &textproto.Error{Code: 552, Msg: "Message exceeded maximum size"}
	ErrForwardingFailed      = &textproto.Error{Code: 554, Msg: "Forwarding failed"}
)

var ErrServerClosed = errors.New("smtp: Server closed")

ErrServerClosed is returned by the Server's Serve and ListenAndServe, methods after a call to Shutdown.

Functions

func LocalAddrFromContext

func LocalAddrFromContext(ctx context.Context) net.Addr

LocalAddrFromContext can be used in handlers to access the local address the connection arrived on. If no local address is available, nil is returned.

Types

type Envelope

type Envelope struct {
	Sender     string
	Recipients []string
	Header     textproto.MIMEHeader
	Data       []byte
}

Envelope holds a message, its headers and recipients. The Header field is read-only and updates to it are not reflected in Data.

func (*Envelope) AddReceivedLine

func (env *Envelope) AddReceivedLine(peer Peer)

AddReceivedLine prepends a Received header to the Data

type Peer

type Peer struct {
	Addr       net.Addr             // Network address
	TLS        *tls.ConnectionState // TLS Connection details, if on TLS
	HeloName   string               // Server name used in HELO/EHLO command
	Username   string               // Username from authentication, if authenticated
	Password   string               // Password from authentication, if authenticated
	Protocol   Protocol             // Protocol used, SMTP or ESMTP
	ServerName string               // A copy of Server.Hostname
}

Peer represents the client connecting to the server

type Protocol

type Protocol string

Protocol represents the protocol used in the SMTP session

const (
	// SMTP
	SMTP Protocol = "SMTP"

	// Extended SMTP
	ESMTP = "ESMTP"
)

type Server

type Server struct {
	Hostname       string // Server hostname. (default: "localhost.localdomain")
	WelcomeMessage string // Initial server banner. (default: "<hostname> ESMTP ready.")

	ReadTimeout  time.Duration // Socket timeout for read operations. (default: 60s)
	WriteTimeout time.Duration // Socket timeout for write operations. (default: 60s)
	DataTimeout  time.Duration // Socket timeout for DATA command (default: 5m)

	MaxConnections int // Max concurrent connections, use -1 to disable. (default: 100)
	MaxMessageSize int // Max message size in bytes. (default: 10240000)
	MaxRecipients  int // Max RCPT TO calls for each envelope. (default: 100)

	// New e-mails are handed off to this function.
	// Can be left empty for a NOOP server.
	// If an error is returned, it will be reported in the SMTP session.
	Handler func(ctx context.Context, peer Peer, env Envelope) error

	// Enable various checks during the SMTP session.
	// Can be left empty for no restrictions.
	// If an error is returned, it will be reported in the SMTP session.
	// Use the Error struct for access to error codes.
	ConnectionChecker func(ctx context.Context, peer Peer) error              // Called upon new connection.
	HeloChecker       func(ctx context.Context, peer Peer, name string) error // Called after HELO/EHLO.
	SenderChecker     func(ctx context.Context, peer Peer, addr string) error // Called after MAIL FROM.
	RecipientChecker  func(ctx context.Context, peer Peer, addr string) error // Called after each RCPT TO.

	// Enable PLAIN/LOGIN authentication, only available after STARTTLS.
	// Can be left empty for no authentication support.
	Authenticator func(ctx context.Context, peer Peer, username, password string) error

	EnableXCLIENT       bool // Enable XCLIENT support (default: false)
	EnableProxyProtocol bool // Enable proxy protocol support (default: false)

	TLSConfig *tls.Config // Enable STARTTLS support.
	ForceTLS  bool        // Force STARTTLS usage.

	ProtocolLogger *log.Logger

	// ConnContext optionally specifies a function that modifies
	// the context used for a new connection c. The provided ctx
	// is derived from the base context.
	ConnContext func(ctx context.Context, c net.Conn) context.Context
	// contains filtered or unexported fields
}

Server defines the parameters for running the SMTP server

func (*Server) Address

func (srv *Server) Address() net.Addr

Address returns the listening address of the server

func (*Server) ListenAndServe

func (srv *Server) ListenAndServe(ctx context.Context, addr string) error

ListenAndServe starts the SMTP server and listens on addr, using ctx as the base context for incoming requests.

func (*Server) Serve

func (srv *Server) Serve(ctx context.Context, l net.Listener) error

Serve starts the SMTP server and listens on l, using ctx as the base context for incoming requests.

func (*Server) Shutdown

func (srv *Server) Shutdown(wait bool) error

Shutdown instructs the server to shutdown, starting by closing the associated listener. If wait is true, it will wait for the shutdown to complete. If wait is false, Wait must be called afterwards.

func (*Server) Wait

func (srv *Server) Wait() error

Wait waits for all client connections to close and the server to finish shutting down.