FBB::Milter(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

✨ FBB::Milter ✨

the manual page for FBB::Milter — section 3bobcat, a.k.a. the Milter interface. Bestie, buckle up, this one's a whole journey and it's lowkey iconic. 💅

💖 NAME 💖

FBB::Milter — Interface to the sendmail mail filter facilities 🦋

🌸 SYNOPSIS 🌸

#include <bobcat/milter>
Linking option: -lmilter -lbobcat

👑 DESCRIPTION 👑

Okay so Milter defines an abstract base class that interfaces to the sendmail mail filter (milter) facilities. It gives you a C++ interface, built on the assumption that a single mail filter program does not implement multiple mail filters. The classic sendmail C-based Milter API uses a (SMFICTX) pointer that represents a mail connection, plus a pointer to connection-specific private data, and that whole situation makes the Milter constructor do a lot of administrative busywork. In a C environment that's fine, whatever, but those administrative tasks distract from the actual main character energy: the Milter's mail filtering functionality. The FBB::Milter class hides all that admin stuff from you, the programmer, so you can focus on filtering mail like a legend. ✨

So the main benefits of Milter are, fr fr:

  • Basic administration is performed by the Milter class 🫶
  • The class' interface is more C++ like than the raw C interface offered by the milter API 💖
  • Administration, allocation and communicating of connection specific data is no longer required 🎀
  • It is not normally necessary to use connection-specific data, like a pointer identifying the connection, anymore when implementing the Milter 🌈
  • Milter uses current-day design patterns enforcing principles of reusable 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 (public) enumerations, bestie. 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:

  • CONNECT — Indicates that the milter defines (overrides) the connection-functionality. This is the first callback function that can be called by sendmail;
  • 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;
  • 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 (initial From ... line) information;
  • 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 (To: ... header address) information;
  • 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;
  • 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;
  • 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;
  • 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;
  • 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;
  • 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;
  • UNKNOWN — Currently not used. Reserved for versions exceeding version 2 of the sendmail milter API;
  • DATA — Currently not used. Reserved for versions exceeding version 3 of the sendmail milter API;
  • 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:

  • NO_FLAGS — No flags are defined;
  • ADD_HEADERS — This flag indicates that the milter is allowed to add headers to the current e-mail message;
  • ADD_RECIPIENTS — This flag indicates that the milter is allowed to add recipients to the current e-mail message;
  • CHANGE_BODY — This flag indicates that the milter is allowed to modify the message's body content;
  • CHANGE_HEADERS — This flag indicates that the milter is allowed to change headers of the current e-mail message;
  • DELETE_RECIPIENTS — This flag indicates that the milter is allowed to remove recipients from the current e-mail message;
  • QUARANTINE — This flag indicates that the milter is allowed to request sendmail to quarantine the current e-mail message;
  • 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:

  • 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;
  • 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;
  • 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;
  • 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);
  • 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:

  • FAILURE — This value is equal to MI_FAILURE, indicating that a C-api function failed to perform its task;
  • SUCCESS — This value is equal to MI_SUCCESS, indicating that a C-api function succeeded in performing its task.

🌈 CONSTRUCTOR/DESTRUCTOR 🌈

  • Milter() — The default constructor is available for derived classes. It performs no actions;
  • virtual ~Milter() — The (public) virtual destructor performs no actions: derived classes can override the destructor to suit their own needs.
Overloaded assignment operators are not available. 🚫

✨ PUBLIC STATIC MEMBER FUNCTIONS ✨

okay bestie these ones are literally the whole soul of the Milter base class — you call them to initialize, start and stop your milter. no biggie. just the entire lifecycle of your daemon. 💖

  • void initialize(std::string const &name, Milter &milter, callback_set callbacks = CONNECT, flag_set flags = NO_FLAGS) — this is the setup era, the glow-up ritual. it initializes the Milter's administration. first arg = the name of the mailfilter. second arg = a reference to a Milter object — and because Milter is an abstract base class, the actual object you pass is always an object of a class derived from Milter. (yes bestie that's the whole point, you subclass it.) third arg = which callbacks to call for this milter, and by default the connect and close callbacks are called. heads up, starting bobcat version 6.04.00: the close callback is always called once a connection ends — you can specify it when you pass the callbacks argument, but if you don't, the close callback still gets called. no escape. 💅 last arg = flags, which specify the Milter's capabilities.
  • std::string const &name() — returns the milter's name. that's it. that's the function. iconic minimalism. 👑
  • bool start() — this one calls smfi_main and takes control of the milter's event loop. returns true if the event loop is successfully terminated.
  • void stop() — shuts down the milter's event loop, but after finishing all threads (polite queen behavior 🫶). once you've called this, start can be called again to continue the milter. it's giving pause-and-resume energy.

🎀 PROTECTED MEMBER FUNCTIONS 🎀

these next ones are non-virtual, and they can be called by members of classes derived from Milter. so basically: your subclass's little private toolbox. 🔧

  • bool addHeader(std::string const &hdrName, std::string const &hdrValue) — only callable from eom, and the ADD_HEADERS flag must have been specified or it will fail. hdrName and hdrValue must both be non-empty strings. each line of the header must be under 2048 characters and should be under 998 characters. need longer headers? make them multi-line, bestie. to make a multi-line header, insert a line feed (\n) followed by at least one whitespace character such as a space or a tab (\t). the line feed should not be preceded by a carriage return. and fr fr, it is the filter writer's responsibility to make sure no standards are violated — that's on you, not on Milter. 😭
  • bool addRecipient(std::string const &rcptName) — only callable from eom, and the ADD_RECIPIENTS flag must have been specified or it will fail.
  • bool changeHeader(std::string const &hdrName, size_t headerNr, std::string const &hdrValue) — only callable from eom, and the CHANGE_HEADERS flag must have been specified or it will fail. see addHeader for the header-requirements (yes, all of them, same rules). headerNr 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 brand new hdrName-header will be added. and if hdrValue is empty? the header gets deleted. gone. no trace. 💀
  • bool deleteRecipient(std::string const &rcptName) — only callable from eom, and the DELETE_RECIPIENTS flag must have been specified or it will fail. this one removes the named recipient from the current message's envelope.
  • SMFICTX *id() const — the Milter object can call this to get a pointer identifying its sendmail-connection. ngl, normally you shouldn't need to call this one. it's the "iykyk, but you probably don't need it" member. 🙈
  • bool insertHeader(size_t hdrIdx, std::string const &hdrName, std::string const &hdrValue) — only callable from eom, and the ADD_HEADERS flag 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. and if headerNr is greater than the number of times hdrName appears, a new hdrName-header will be added. ✨
  • bool openSocket(bool removeIfTrue = true) — call this before start. it attempts to create the socket specified by setConnection (scroll down bestie, it's right there), which lets the calling application make sure the socket can actually be created — and possibly change its protection (access rights) before the milter starts its work. if you don't call it, it will be called implicitly when run is started. returns true if the socket could be created. 🧚
  • bool quarantine(std::string const &reason) — only callable from eom. causes the MTA to quarantine the message using the given reason. it's giving time out, you're in the corner now. 🚫
  • bool replaceBody(std::string const &body) — only callable from eom, and the CHANGE_BODY flag must have been specified or it will fail. it can be called multiple times, in which case the various body contents are concatenated into the final message. newlines should be coded as CRLF.
  • bool setBacklog(size_t backlog = 5) — call this before start. sets the incoming socket backlog used by listen(2). if setBacklog isn't called, the operating system default is used. returns false if the backlog couldn't be set as requested. and it is the programmer's responsibility not to call this function with a 0 argument — do not do it, bestie, that's on you. 😤
  • bool setConnection(std::string const &name) — call this before start. sets the socket through which the filter communicates with sendmail. the socket can be specified using one of these 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.

okay this part is important: possible failure of this function cannot be determined from its return value. instead, run will fail. so don't be out here trusting that return value, bestie. 💀
  • setReply(std::string const &rcode, std::string const &xcode = "", std::string const &msg = "") — sets the default SMTP error reply code. it can be called from any callback member, except connect. rcode should be a three-digit (RFC 821/2821) SMTP reply code, and it must be a valid 4XX or 5XX reply code. xcode, when specified, must be an extended (RFC 1893/2034) reply code. msg may be an additional textual message. heads up: the Milter class has no member comparable to the libmilter API function smfi_setmlreply. the Milter class. (that's how the original ends the sentence, and honestly same, it just. stops there. 😭)
  • void setTimeout(size_t seconds = 7210) — call this before start. sets the number of seconds libmilter will wait for an MTA connection before timing out a socket. if setTimeout isn't called, a default timeout of 7210 seconds is used. and again: it is the programmer's responsibility not to call this function with an argument equal to 0. ⏰
  • char const *symval(std::string const &name) const — returns the value of a specific sendmail macro. name should be set to the name of a sendmail macro. single letter macros can optionally be enclosed in braces ({ and }), but longer macro names must be enclosed in braces, just as in a sendmail.cf file. 0 is returned if the macro isn't defined. by default, these 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, until the end of the message for the third set (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. 🌸

  • bool wait() — only callable from eom. tells the MTA that the filter is still working on a message, which causes the MTA to re-start its timeouts. hold on hold on i'm not done yet energy. ✋

💅 PRIVATE VIRTUAL MEMBER FUNCTIONS ✨

okay bestie, this is the part where it gets juicy 🌸 — everything left in class Milter is only useful for Milter implementations living in classes derived from Milter. These members below can be overridden by derived classes. And heads up, icon: clone must be overridden. No skipping, no negotiating. 💀

Except for clone, every single member in this section is a callback function. Which means: the MTA calls them to process parts of the mail message. And they come in three flavors, and yes we're distinguishing them like a true main character 👑

  • Recipient-oriented callbacks (recipient, see below) can 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 — and during that one connection, multiple messages may be delivered to multiple sets of recipients. multitasking queen 💅
  • The remaining callbacks are message-oriented, affecting the processing of a single message to all its recipients.
  • 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 reclaims any resources allocated on a per-message basis — and no, that's not the connection specific data, that's the derived class' destructor's whole job, stay in your lane. abort must be tolerant of being called between any two message-oriented callbacks. It's only called if the message gets aborted outside the filter's control and the filter hasn't completed its message-oriented processing. For example: if a filter has already returned ACCEPT, REJECT, or DISCARD from a message-oriented routine, abort won't be called, even if the message is later aborted outside its control. your fave is ghosted 😭
  • 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 0-terminated. Also, the sequence may contain 0-characters. And since message bodies can be very large, defining body can significantly impact filter performance — this is giving "heavy is the head that wears the crown" 👑. 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. fr fr, chunk by chunk 🍓
  • virtual Milter *clone() const = 0 — this pure virtual function must be implemented by derived classes, and it returns a newly allocated copy of the derived object passed to the initialize static member. It's used by the standard virtual constructor design pattern. Destruction of the allocated object is the responsibility of clone's caller — so like, you allocated it, you're the parent now, do your duty 🫶
  • 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 connect is called. Here's the lore: 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. So yes, it can be the only callback ever used for a given connection, and developers should anticipate this possibility when crafting their close code. close is called on close even if the previous mail transaction was aborted. The default implementation of the member close is
sfsistat Milter::close()
{
    smfi_setpriv(d_ctx, 0);         // delete this d_ctx data

    return CONTINUE;
}

By calling smfi_setpriv with second argument 0, any data associated with the current connection is deleted by the milter. Implementations overriding close should at least call smfi_setpriv, passing the value returned by the member id (cf. section PROTECTED MEMBER FUNCTIONS) as first argument and 0 as second argument. Other data managed by the milter and specifically associated with a connection should be accessed via the connection's id — e.g. using a std::unordered_map using an SMFICTX * as key. it's giving keyed lookup realness 🔑

  • 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 the 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's 0 if the type isn't supported in the current version, or if the SMTP connection is made via stdin. sometimes the answer is just 0 bestie 💀
  • virtual sfsistat data() — Not yet supported. Will be available with libmilter versions beyond 3. yea she's not here yet, manifesting ✨
  • virtual sfsistat eoh() — this message-oriented member is called once after all headers have been processed. end of headers, end of an era 🌈
  • 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 can modifications to the message headers, body, and envelope be made (see the add-, change- and delete- members listed below). one function to rule them all 👑
  • virtual sfsistat header(char *headerf, char *headerv) — this message-oriented member is called zero or more times between recipient and eoh, once for each e-mail 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. yes that space before sender is real, don't @ me 🙈

  • 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. so basically it's the wild west out here 🤠
  • virtual sfsistat recipient(char **argv) — this recipient-oriented member is called once per recipient (provided by the To: or Cc: headers), 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. Here's the response tea ☕:
    • TEMPFAIL may be returned, to 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 ESMTP responses are described in RFC 1869. iykyk 📬

  • 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 (provided in the e-mail's initial From ... line). Later arguments are the ESMTP arguments. And the response menu 🍽️:
    • 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 ESMTP responses are described in RFC 1869.

  • virtual sfsistat unknown(char *ptr) — Not yet supported. Will be available with libmilter versions beyond 2. mystery member, she's mysterious 💜

🌸 EXAMPLE 🌸

To do

literally just vibes in there. no cap, that's the whole thing. 😭

🎀 FILES 🎀

  • bobcat/milter — defines the class interface

✨ SEE ALSO ✨

go read the RFCs bestie, they're long but they're iconic 📚🦋

💀 BUGS 💀

  • -lmilter must be specified before -lbobcat.
order matters, always. put her first or she throws a fit 🙈

🫶 BOBCAT PROJECT FILES 🫶

  • https://fbb-git.gitlab.io/bobcat/: gitlab project page;
  • Debian Bobcat project files:
    • libbobcat6: debian package containing the shared library, changelog and copyright note;
    • libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

👑 BOBCAT 👑

Bobcat is an acronym of `Brokken's Own Base Classes And Templates'. cute name, ate 💅

This is free software, distributed under the terms of the GNU General Public License (GPL).

free as in freedom, slay 🕊️

⭐ AUTHOR ⭐

Frank B. Brokken (f.b.brokken@rug.nl).

and that's a wrap bestie 🥰 this page lives in libbobcat-dev_6.15.01, dated 2005-2026, brought to you by FBB — FBB::Milter(3bobcat). go forth and filter those mails, you absolute legend 🦋💖✨

📦 where this page comes from