Provided by: libbobcat-dev_4.08.02-2build1_amd64 
NAME
FBB::Milter - Interface to the sendmail mail filter facilities
SYNOPSIS
#include <bobcat/milter>
Linking option: -lmilter -lbobcat
DESCRIPTION
Milter defines an abtract base class interfacing to the sendmail mail filter (milter)
facilities. It defines a C++ interface, based on the assumption that a single mail filter
program does not implement multiple mail filters. The traditional sendmail C-based Milter
API uses a (SMFICTX) pointer representing a mail connection, and a pointer to
connection-specific `private’ data, requiring the Milter constructor to perform quite a
few administrative tasks. While acceptable in a C environment these administratve tasks
distract from the main task: the Milter’s mail filtering functionality. The FBB::Milter
class hides these administrative tasks from the programmer, who is then able to
concentrate on filtering mail. The main benefits of Milter are therefore
o Basic administration is performed by the Milter class
o The class’ interface is more C++ like than the raw C interface offered by the
milter API.
o Administration, allocation and communicating of connection specific data is no
longer required
o It is not normally necessary to use connection-specific data, like a pointer
identifying the connection, anymore when implementing the Milter.
o Milter uses current-day design patterns enforcing principles of reuable software,
thus simplifying the construction of the actual Milter. To activate a milter from
the sendmail.mc configuration file, use, e.g., INPUT_MAIL_FILTER(`name’,
`S=socket’), where name is the milter’s name, and socket is the name of the socket.
See also the setConnection member below.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are
defined in the namespace FBB.
INHERITS FROM
-
ENUMERATIONS
The class defines four enumerations. One enumeration is used to indicate the
callback-functions that need to be called, the second one renames the flags that can be
passed to sendmail to indicate which actions the milter is allowed to perform. The third
one defines status values that may be used to inform sendmail how to further process a
message. The fourth one defines return values. The enumerations are:
enum CallBack
This enumeration holds the following values:
o CONNECT:
Indicates that the milter defines (overrides) the connection-functionality. This is
the first callback function that can be called by sendmail.
o HELO:
Indicates that the milter defines (overrides) the helo-functionality. This
indicates that the helo function should be called by sendmail, providing the milter
with information about the connecting client.
o SENDER:
Indicates that the milter defines (overrides) the sender-functionality. This
indicates that the sender function should be called by sendmail, providing the
milter with the sender’s envelope information.
o RECIPIENT:
Indicates that the milter defines (overrides) the recipient-functionality. This
indicates that the recipient function should be called by sendmail, providing the
milter with the recipient’s envelope information.
o HEADER:
Indicates that the milter defines (overrides) the header-functionality. This
indicates that the header function should be called by sendmail for each mail
header that is used in the current mail message.
o EOH:
Indicates that the milter defines (overrides) the end-of-header-functionality. This
indicates that the eoh function should be called by sendmail once all header lines
have been processed.
o BODY:
Indicates that the milter defines (overrides) the body-functionality. This
indicates that the body function should be called by sendmail, offering the
mail-body to the milter.
o EOM:
Indicates that the milter defines (overrides) the end-of-message-functionality.
This indicates that the eom function should be called by sendmail, once all
elements of the e-mail message have been processed.
o ABORT:
Indicates that the milter defines (overrides) the abort-functionality. The abort
function may be called by sendmail before eom is called. It should reclaim all
resources used by the message, but not delete any memory allocated by the milter,
as this is close’s job.
o CLOSE:
Indicates that the milter defines (overrides) the close-functionality. The close
function should delete all (connection specific) memory allocated by the milter. It
may be called `out-of-order’, i.e. even before connect is called and developers
should anticipate this possibility when crafting their close code. In particular,
it is incorrect to assume the private context pointer will be something other than
0 in this callback.
o UNKNOWN:
Currently not used. Reserved for versions exceeding version 2 of the sendmail
milter API
o DATA:
Currently not used. Reserved for versions exceeding version 3 of the sendmail
milter API
o ALL_CALLBACKS:
Shortcut to indicate all callback facilities. The CallBack values are bit-flags.
The bit_or operator may be used to combine them, and the bit_not operator may be
used to remove a flag from ALL_CALLBACKS (e.g., ALL_CALLBACKS && ~ABORT).
enum Flags
This enumeration holds the following values:
o NO_FLAGS:
No flags are defined.
o ADD_HEADERS:
This flag indicates that the milter is allowed to add headers to the current e-mail
message.
o ADD_RECIPIENTS:
This flag indicates that the milter is allowed to add recipients to the current
e-mail message.
o CHANGE_BODY:
This flag indicates that the milter is allowed to modify the message’s body
contents.
o CHANGE_HEADERS:
This flag indicates that the milter is allowed to change headers of the current
e-mail message.
o DELETE_RECIPIENTS:
This flag indicates that the milter is allowed to remove recipients from the
current e-mail message.
o QUARANTINE:
This flag indicates that the milter is allowed to request sendmail to quarantine
the current e-mail message.
o ALL_FLAGS:
Shortcut to indicate all callback facilities. The Flags values are bit-flags. The
bit_or operator may be used to combine them, and the bit_not operator may be used
to remove a flag from ALL_FLAGS (e.g., ALL_FLAGS && ~QUARANTINE).
Status
This enumeration simplifies the extended SMFIS_ values used by the C API. These values may
be used to return sfsistat values:
o ACCEPT:
This value is equal to SMFIS_ACCEPT, indicating that Sendmail should accept the
message. For a connection-oriented callback (see below at PROTECTED VIRTUAL MEMBER
FUNCTIONS), accept this connection without further filter processing, call close
(see below). For other callbacks: accept this message without further filtering.
o CONTINUE:
This value is equal to SMFIS_CONTINUE, indicating that Sendmail should continue
processing. This is the default for all callback functions which are not overridden
by the class derived from Milter.
o DISCARD:
This value is equal to SMFIS_DISCARD, indicating that Sendmail should discard the
mail message. It should not be returned by a connection-oriented callback. For
other callbacks: the message is accepted, but silently discarded.
o REJECT:
This value is equal to SMFIS_REJECT, indicating that Sendmail should reject the
mail message. For a connection-oriented callback, reject this connection; call
close. For a message-oriented callback (except for eom or abort, see below),
reject this message. For a recipient-oriented callback, reject the current
recipient (but continue processing the current message).
o TEMPFAIL:
This value is equal to SMFIS_TEMPFAIL, indicating that Sendmail should return a
`temporary unavailable’ message to the sender of the mail message. For a
message-oriented callback (except sender, see below), fail for this message. For a
connection-oriented callback, fail for this connection and call close. For a
recipient-oriented callback, only fail for the current recipient and continue
message processing.
Return
This enumeration simplifies the extended MI_ values used by the C API. Most return values
used by the Milter class, however, are bool values. The Return values are:
o FAILURE:
This value is equal to MI_FAILURE, indicating that a C-api function failed to
perform its task.
o SUCCESS:
This value is equal to MI_SUCCESS, indicating that a C-api function succeeded in
performing its task.
CONSTRUCTORS
The default- and copy constructors are available for derived classes. They perform no
actions.
PUBLIC STATIC MEMBER FUNCTIONS
These functions form the heart of the Milter base-class. They can be called to initialize,
start and stop the Milter.
o void initialize(std::string const &name, Milter &milter, callback_set callbacks =
CONNECT, flag_set flags = NO_FLAGS):
This function initializes the Milter’s administration. It expects the name of the
mailfilter as its first argument. Its second argument is a reference to a Milter
object. Since Milter is an abstract base class the actual object is always an
object of a class derived from Milter. Its third argument specifies the callbacks
to call for this milter. By default the connect callback will be called. Note that
the close callback is not called by default. This is ok, since the Milter object
doesn’t have to cleanup `private’ data, as is normal with the C API. The last
argument defines flags, specifying the Milter’s capabilities.
o std::string const &name():
This function returns the milter’s name.
o bool start():
This member function calls smfi_main, controlling the milter’s event loop. It
returns true if the event-loop is successfully terminated.
o void stop():
This member function terminates the milter’s event loop, after finishing all
threads. Following this call start may be called again to continue the milter.
PROTECTED VIRTUAL MEMBER FUNCTIONS
The remaining functionality of the class Milter is useful only for Milter-implementations
in classes derived from Milter. The following members can be overridden by derived
classes. Note that clone must be overridden. Except for clone, all the members in this
sections are callback functions. I.e., the MTA will call them to process parts of the mail
message. Recipient-, message-, and connection-oriented callbacks are distinguished.
The recipient-oriented callback (recipient, see below) may affect the processing of a
single message to a single recipient. Connection-oriented callbacks (connect, helo and
close) affect the processing of the entire connection (during which multiple messages may
be delivered to multiple sets of recipients). The remaining callbacks are
message-oriented, affecting the processing of a single message to all its recipients.
o virtual sfsistat abort():
This message-oriented member may be called at any time during message processing
(i.e. between some message-oriented routine and eom). abort reclaim any resources
allocated on a per-message basis (which are not the connection specific data, which
should be handled by the derived class’ destructor), and must be tolerant of being
called between any two message-oriented callbacks. abort is only called if the
message is aborted outside the filter’s control and the filter has not completed
its message-oriented processing. For example, if a filter has already returned
ACCEPT, REJECT, or DISCARD from a message-oriented routine, abort will not be
called even if the message is later aborted outside its control.
o virtual sfsistat body(unsigned char *text, size_t length):
This message-oriented member is called zero or more times between eoh and eom.
text points to a sequence of bytes. It is not necessarily a 0-terminated. Moreover,
the sequence may contain 0-characters. Since message bodies can be very large,
defining body can significantly impact filter performance. End-of-lines are
represented as received from SMTP (normally CR/LF). Later filters will see body
changes made by earlier ones, and message bodies may be sent in multiple chunks,
with one call to body per chunk.
o virtual Milter *clone() const = 0:
This pure virtual function must be implemented by derived classes to return a newly
allocated copy of the derived object passed to the initialize static member. It is
used by the standard `virtual constructor’ design pattern. The destruction of the
allocated object is the responsibility of clone’s caller.
o virtual sfsistat close():
This connection-oriented member is always called once at the end of each
connection. It may be called "out-of-order", i.e. before even the connect is
called. After a connection is established by the MTA to the filter, if the MTA
decides this connection’s traffic will be discarded (e.g. via an access_db result),
no data will be passed to the filter from the MTA until the client closes down. At
that time, close is called. It can therefore be the only callback ever used for a
given connection, and developers should anticipate this possibility when crafting
their close code. The member close is called on close even if the previous mail
transaction was aborted.
o virtual sfsistat connect(char *hostname, _SOCK_ADDR *hostaddr):
This connection-oriented member may be called once, at the start of each SMTP
connection. The parameter hostname is he host name of the message sender, as
determined by a reverse lookup on the host address. If the reverse lookup fails,
hostname will contain the message sender’s IP address enclosed in square brackets
(e.g. [a.b.c.d]). The parameter hostaddr is the host address, as determined by a
getpeername(2) call on the SMTP socket. It is 0 if the type is not supported in the
current version or if the SMTP connection is made via stdin.
o virtual sfsistat data():
Not yet supported. Will be available with libmilter versions beyond 3.
o virtual sfsistat eoh():
This message-oriented member is called once after all headers have been processed.
o virtual sfsistat eom():
This message-oriented member is called once after all calls to body for a given
message have been completed. Note that only in this function modifications to the
message headers, body, and envelope can be made (see the add-, change- and delete-
members listed below).
o virtual sfsistat header(char *headerf, char *headerv):
This message-oriented member is called zero or more times between recipient and
eoh, once per message header. The headerf parameter contains the text of the
header, the headerv parameter contains its value. E.g., if an e-mail message
contains the following headers:
From: sender <f@example.com>
Subject:no
then header will be called twice with the following values for, respectively
headerf and headerv:
First header: "From", " sender <f@example.com>"
Second header: "Subject", "no"
Further details about header information is given in RFC 882.
o virtual sfsistat helo(char *helohost):
This connection-oriented member is called whenever the client sends a HELO/EHLO
command. It may therefore be called between zero and three times. The helohost
parameter should be the domain name of the sending host (but is, in practice,
anything the sending host wants to send).
o virtual sfsistat recipient(char **argv):
This recipient-oriented member is called once per recipient, hence one or more
times per message, immediately after sender. The parameter argv is a 0-terminated
array of pointers to SMTP command arguments; argv[0] is guaranteed to be the
recipient address. Later arguments are the ESMTP arguments. TEMPFAIL may be
returned indicate that sendmail should return a temporary failure for this
particular recipient; further recipients may still be sent, abort is not called.
REJECT will reject this particular recipient; further recipients may still be sent,
abort is not called. DISCARD will accept (but discard) the message, abort will be
called. ACCEPT will accept recipient, abort will not be called. More details on
ESTMP responses, are described in RFC 1869.
o virtual sfsistat sender(char **argv):
This message-oriented member is called once at the beginning of each message,
before recipient. argv[0] is guaranteed to be the sender’s envelope address. Later
arguments are the ESMTP arguments. TEMPFAIL may be returned, indicating that
sendmail should return a temporary failure for this particular message, abort is
not called. REJECT will reject this message, abort is not called. DISCARD will
accept (but discard) the message, abort will be called. ACCEPT will accept
recipient, abort will not be called. More details on ESTMP responses, are described
in RFC 1869.
o virtual sfsistat unknown(char *ptr):
Not yet supported. Will be available with libmilter versions beyond 2.
PROTECTED MEMBER FUNCTIONS
The following members are non-virtual. They can be called by members of classes derived
from Milter:
o bool addHeader(std::string const &hdrName, std::string const &hdrValue):
This member may only be called from eom, and the flag ADD_HEADERS must have been
specified or it will fail. The hdrName and hdrValue must be non-empty strings.
Each line of the header must be under 2048 characters and should be under 998
characters. If longer headers are needed, make them multi-line. To make a
multi-line header, insert a line feed (\n) followed by at least one whitespace
character such as a space or tab (\t). The line feed should not be preceded by a
carriage return. It is the filter writer’s responsibility to ensure that no
standards are violated.
o bool addRecipient(std::string const &rcptName):
This member may only be called from eom, and the flag ADD_RECIPIENTS must have been
specified or it will fail.
o bool changeHeader(std::string const &hdrName, size_t headerNr, std::string const
&hdrValue):
This member may only be called from eom, and the flag CHANGE_HEADERS must have been
specified or it will fail. See addHeader for the header-requirements. The headerNr
parameter is a 1-based header index value. A headerNr value of 1 will modify the
first occurrence of a header named hdrValue. If headerNr is greater than the number
of times hdrName appears, a new hdrName-header will be added. If hdrValue is empty,
the header is deleted.
o bool deleteRecipient(std::string const &rcptName):
This member may only be called from eom, and the flag DELETE_RECIPIENTS must have
been specified or it will fail. This member removes the named recipient from the
current message’s envelope.
o SMFICTX *id() const:
This member may be called by the Milter object to obtain a pointer identifying its
sendmail-connection. Normally it should not be necessary to call this member.
o bool insertHeader(size_t hdrIdx, std::string const &hdrName, std::string const
&hdrValue):
This member may only be called from eom, and the flag ADD_HEADERS must have been
specified or it will fail. See addHeader for the header-requirements. The headerNr
parameter is a header index value. A headerNr value of 0 will insert this header as
the first of the hdrName headers. If headerNr is greater than the number of times
hdrName appears, a new hdrName-header will be added.
o bool openSocket(bool removeIfTrue = true):
This member should be called before start is called. This member attempts to
create the socket specified by setConnection (see below). This allows the calling
application to ensure that the socket can be created, possibly changing its
protection (access rights) before the milter starts its work. If this member is
not called, it will be called implicitly when run is started. It returns true if
the socket could be created.
o bool quarantine(std::string const &reason):
This member may only be called from eom and causes the MTA to quarantines the
message using the given reason.
o bool replaceBody(std::string const &body):
This member may only be called from eom, and the flag CHANGE_BODY must have been
specified or it will fail. It may be called multiple times in which case the
various body contents are concatenated in the final message. Newlines should be
coded as CRLF.
o bool setBacklog(size_t backlog = 5):
This member should be called before start is called. Sets the incoming socket
backlog used by listen(2). If setBacklog is not called, the operating system
default is used. The function returns false if the backlog could not be set as
requested. It is the responsibility of the programmer not to call this function
with a 0 argument.
o bool setConnection(std::string const &name):
This member should be called before start is called. Sets the socket through which
the filter communicates with sendmail. The socket may be specified using one of
the following variants:
{unix|local}:/path/to/file - A named pipe;
net:port@{hostname|ip-address} - An IPV4 socket;
inet6:port@{hostname|ip-address} - An IPV6 socket.
If possible, filters should not run as root when communicating over unix/local
domain sockets.
Unix/local sockets should have their permissions set to 0600 (read/write permission
only for the socket’s owner) or 0660 (read/write permission for the socket’s owner
and group) which is useful if the sendmail RunAsUser option is used. The
permissions for a unix/local domain socket are determined as usual by umask, which
should be set to 007 or 077.
Possible failure of this function cannot be determined from its return value.
Rather, run will fail.
o setReply(std::string const &rcode, std::string const &xcode = "", std::string const
&msg = ""):
This member sets the default SMTP error reply code. It may be called from any
callback member, except connect. The parameter rcode should be a he three-digit
(RFC 821/2821) SMTP reply code and it must be a valid 4XX or 5XX reply code. The
parameter xcode, when specified, must be a extended (RFC 1893/2034) reply code. The
parameter msg may be an additional textual message. The Milter class has no member
comparable to the libmilter API function smfi_setmlreply. the Milter class.
o void setTimeout(size_t seconds = 7210):
This member should be called before start is called. Sets the number of seconds
libmilter will wait for an MTA connection before timing out a socket. If setTimeout
is not called, a default timeout of 7210 seconds is used. It is the responsibility
of the programmer not to call this function with an argument equal to 0.
o char const *symval(std::string const &name) const:
This member returns the value of a specific sendmail macro. The name parameter
should be set to he name of a sendmail macro . Single letter macros can optionally
be enclosed in braces ({ and }), longer macro names must be enclosed in braces,
just as in a sendmail.cf file.0 is returned if the macro is not defined. By
default, the following macros are valid in the given contexts:
for connect: daemon_name, if_name, if_addr, j, _;
for helo: tls_version, cipher, cipher_bits, cert_subject, cert_issuer;
for sender: i, auth_type, auth_authen, auth_ssf, auth_author, mail_mailer,
mail_host, mail_addr;
for recipient: rcpt_mailer, rcpt_host, rcpt_addr.
All macros stay in effect from the point they are received until the end of the
connection for the first two sets, the end of the message for the third (sender),
and just for each recipient for the final set (recipient).
The following macros may be specified in the sendmail.mc configuration file:
define(`confMILTER_MACROS_CONNECT’, `m1’, ...), define(`confMILTER_MACROS_HELO’,
...), define(`confMILTER_MACROS_ENVFROM’, ...), define(`confMILTER_MACROS_ENVRCPT’,
...), where `m1’, ... represents a comma separated list of returnable macros.
Single letter macros can optionally be enclosed in braces ({ and }), longer macro
names must be enclosed in braces.
o bool wait():
This member may only be called from eom and tells the MTA that the filter is still
working on a message, causing the MTA to re-start its timeouts.
EXAMPLE
To do
FILES
bobcat/milter - defines the class interface
SEE ALSO
bobcat(7), getpeername(2), listen(2),
http://www.milter.org (e.g., http://www.milter.org/developers/api)
http://sendmail.org/m4/readme.html
http://rfc.net/rfc821.html
http://rfc.net/rfc822.html
http://rfc.net/rfc1869.html
http://rfc.net/rfc1893.html
http://rfc.net/rfc2034.html
http://rfc.net/rfc2821.html
/usr/include/libmilter/mfapi.h
BUGS
-lmilter must be specified before -lbobcat.
DISTRIBUTION FILES
o bobcat_4.08.02-x.dsc: detached signature;
o bobcat_4.08.02-x.tar.gz: source archive;
o bobcat_4.08.02-x_i386.changes: change log;
o libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_4.08.02-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License
(GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).