NAME

       filter_api_loop,   filter_api_accept,   filter_api_reject,   filter_api_reject_code,  filter_api_writeln,
       filter_api_on_connect, filter_api_on_helo,  filter_api_on_mail,  filter_api_on_rcpt,  filter_api_on_data,
       filter_api_on_dataline,       filter_api_on_eom,      filter_api_on_reset,      filter_api_on_disconnect,
       filter_api_on_commit,      filter_api_on_rollback,       filter_api_setugid,       filter_api_set_chroot,
       filter_api_no_chroot,     filter_api_set_udata,     filter_api_get_udata,    filter_api_sockaddr_to_text,
       filter_api_mailaddr_to_text — filter API for smtpd

SYNOPSIS

       #include <smtpd-defines.h>
       #include <smtpd-api.h>

       void
       filter_api_loop(void);

       int
       filter_api_accept(uint64_t id);

       int
       filter_api_reject(uint64_t id, enum filter_status status);

       int
       filter_api_reject_code(uint64_t id, enum filter_status status, uint32_t code, const char *line);

       void
       filter_api_writeln(uint64_t id, const char * line);

       void
       filter_api_on_connect(int(*cb)(uint64_t, struct filter_connect *));

       void
       filter_api_on_helo(int(*cb)(uint64_t, const char *));

       void
       filter_api_on_mail(int(*cb)(uint64_t, struct mailaddr *));

       void
       filter_api_on_rcpt(int(*cb)(uint64_t, struct mailaddr *));

       void
       filter_api_on_data(int(*cb)(uint64_t));

       void
       filter_api_on_dataline(void(*cb)(uint64_t, const char *));

       void
       filter_api_on_eom(int(*cb)(uint64_t, size_t));

       void
       filter_api_on_reset(void(*cb)(uint64_t));

       void
       filter_api_on_disconnect(void(*cb)(uint64_t));

       void
       filter_api_on_commit(void(*cb)(uint64_t));

       void
       filter_api_on_rollback(void(*cb)(uint64_t));

       void
       filter_api_setugid(uid_t uid, gid_t gid);

       void
       filter_api_set_chroot(const char *rootpath);

       void
       filter_api_no_chroot(void);

       void
       filter_api_set_udata(uint64_t id, void *data);

       void *
       filter_api_get_udata(uint64_t id);

       const char *
       filter_api_sockaddr_to_text(const struct sockaddr *sa);

       const char *
       filter_api_mailaddr_to_text(const struct mailaddr *maddr);

DESCRIPTION

       filter_api is an interface intended to provide filter capabilities for the smtpd(8)  daemon.   filter_api
       is  used in standalone filter programs, which setup callback functions to hook into the SMTP dialog.  For
       example, each SMTP command can be intercepted with callback functions.

       The function filter_api_loop() is used to enter the filter loop, waiting for  callback  functions  to  be
       called.

       The  function  filter_api_accept()  can  be  called  to accept the current message with the given id from
       within a callback function.

       The functions filter_api_reject() and filter_api_reject_code()  can  be  called  to  reject  the  current
       message  with the given id from within a callback function.  Both expect the status to be specified which
       should be one of the following values.

       FILTER_FAIL
            The filter failed and the message should not be accpeted.

       FILTER_CLOSE
            The filter is done and the message should not be accepted.

       Morover, with the function filter_api_reject_code() a code and line  can  be  specified,  to  reject  the
       current message with a custom SMTP reply code and error message.

       The  function  filter_api_writeln()  is  intended to write (received) SMTP DATA command lines (back) from
       within a callback function.  This might be used by a filter to add or modifiy DATA lines.

CALLBACK FUNCTIONS

       The function filter_api_on_connect() is called on new SMTP connections.  The  callback  can  be  used  to
       accept or reject messages based on the given connection information.

       The  function filter_api_on_helo() is called on SMTP HELO command.  The callback can be used to accept or
       reject messages based on the given HELO string.

       The function filter_api_on_mail() is called on SMTP MAIL FROM command.   The  callback  can  be  used  to
       accept or reject messages based on the given MAIL FROM address.

       The  function filter_api_on_rcpt() is called on SMTP RCPT TO command.  The callback can be used to accept
       or reject messages based on the given RCPT TO address.

       The function filter_api_on_data() is called on SMTP DATA command.  The callback might be  used  to  setup
       data structures for filtering the upcoming DATA lines.

       The  function  filter_api_on_dataline()  is  called  on each SMTP DATA line.  The callback can be used to
       accept or reject messaged based on the (header or body) content of the current message.

       The function filter_api_on_eom() is called on the end (of DATA command)  of  the  current  message.   The
       callback might be used to cleanup data structures and finalize the decision of accepting or rejecting the
       message.

       The  function  filter_api_on_reset() is called on SMTP RSET command.  The callback might be used to reset
       the current filter state.

       The function filter_api_on_disconnect() is called on closed SMTP connections.  The callback might be used
       to cleanup earlier setup data structures.

       The function filter_api_on_commit() is called on commit of the current message.

       The function filter_api_on_rollback() is called on rollback of the SMTP session.  The callback  might  be
       used to cleanup earlier setup data structures.

HELPER FUNCTIONS

       The  function  filter_api_setugid()  can be called using uid and gid to set the running user and group of
       the filter.

       The function filter_api_set_chroot() can be called using rootpath to set the chroot path of the filter.

       The function filter_api_no_chroot() can be called to disable chroot for the filter.

       The function filter_api_set_udata() can be called for the current message with the given id to set a user
       data pointer data from within a callback function.

       The function filter_api_get_udata() can be called to get the user data pointer for  the  current  message
       with the given id from within a callback function.

       The function filter_api_sockaddr_to_text() can be called to convert a socket address sa to a string.

       The function filter_api_mailaddr_to_text() can be called to convert a mail address maddr to a string.

RETURN VALUES

       The  functions filter_api_accept(), filter_api_reject(), and filter_api_reject_code(), return 1, intended
       to be used in a return statement of a callback function.

       The function filter_api_get_udata() returns a pointer to the user data set for the current message.

       The functions filter_api_sockaddr_to_text() and  filter_api_mailaddr_to_text()  return  a  pointer  to  a
       static  buffer containing the string representation.  The buffer remains valid until the next call to the
       conversion functions.  In case of error, the function filter_api_sockaddr_to_text()  returns  the  static
       string “(unknown)” and the function filter_api_mailaddr_to_text() returns NULL.

ERRORS

       The  function  filter_api_sockaddr_to_text()  may  fail  for  any of the errors specified for the routine
       getnameinfo(3) and listed in gai_strerror(3).

EXAMPLES

       filter-stub(8) which ships with OpenSMTPD-extras is intended to provide an example code template.

SEE ALSO

       smtpd.conf(5), smtpd(8), filter-stub(8)

Debian                                            June 11, 2015                                    FILTER_API(3)