osmtpd_run3

Usage

Overview

The osmtpd API is an event based interface for writing smtpd(8) filters. Filter and report callbacks are registered via the osmtpd_register class of functions, followed by osmtpd_run. A callback should return 0 in the case of success, or -1 in the case of error which leads to disconnect of this session.

osmtpd_run starts the communication with the server and transforms network queries to callbacks. Internally it uses event_dispatch(3), which allows filters to be written fully asynchronously.

Each callback cb gets at least a pointer of the type struct, osmtpd_ctx. It contains the following elements:

enum osmtpd_type type

The type of request being made. The possible values are OSMTPD_TYPE_FILTER and OSMTPD_TYPE_REPORT.

enum osmtpd_phase phase

The phase in the transaction which triggered the callback. The following values match their respective osmtpd_register function:

int version_major

The major version number of the protocol. Most filters don't need this information.

int version_minor

The minor version number of the protocol. Most filters don't need this information.

struct timespec tm

The time the event was triggered inside smtpd(8).

int incoming

Set to 1 if the event was based on an incoming connection, 0 if it's an outgoing connection. The osmtpd_register_filter class of functions is always based on incoming connections. osmtpd_register_report can be both incoming and outgoing.

uint64_t reqid

The request ID of the connection the event was issued on. This value can be useful for logging. Filters in need of filter specific data can use osmtpd_local_session and local_session.

uint64_t token

The filter specific token. Most filters don't need this information.

struct sockaddr_storage src

The source address and port of the connection. This needs to be cast to the appropriate sockaddr type based on the ss_family attribute. It can have the following families: AF_INET, AF_INET6 and AF_UNIX. To use this attribute, initialize osmtpd_need with OSMTPD_NEED_SRC. If not available the entire attribute is zeroed out.

struct sockaddr_storage dst

The destination address and port of the connection. This needs to be cast to the appropriate sockaddr type based on the ss_family attribute. It can have the following families: AF_INET, AF_INET6 and AF_UNIX. To use this attribute, initialize osmtpd_need with OSMTPD_NEED_DST. If not available the entire attribute is zeroed out.

char *rdns

The reverse DNS hostname of the connection. To use this attribute, initialize osmtpd_need with OSMTPD_NEED_RDNS. If not available the attribute is set to NULL.

enum osmtpd_status fcrdns

Whether the reverse DNS hostname is forward confirmed. To use this attribute, initialize osmtpd_need with OSMTPD_NEED_FCRDNS. If not available the attribute is set to OSMTPD_STATUS_TEMPFAIL.

char *identity

The identity of the remote host as presented by the HELO or EHLO SMTP command. To use this attribute, initialize osmtpd_need with OSMTPD_NEED_IDENTITY. If not available the attribute is set to NULL.

char *ciphers

The ciphers used during (start)tls. To use this attribute, initialize osmtpd_need with OSMTPD_NEED_CIPHERS. If not available the attribute is set to NULL.

uint32_t msgid

The message ID of the current message being handled in the SMTP transaction. This value can be useful for logging. osmtpd_need needs to be initialized with OSMTPD_NEED_MSGID. If not available the attribute is set to 0. Filters in need of filter specific data can use osmtpd_local_message and local_message.

char *username

The username with which the session was successfully authenticated. osmtpd_need needs to be initialized with If not available or authentication failed is set to NULL.

char *mailfrom

The envelope MAIL FROM address in the SMTP transaction. osmtpd_need needs to be initialized with OSMTPD_NEED_MAILFROM. If not available the attribute is set to NULL.

char **rcptto

The envelope RCPT TO address in the SMTP transaction. osmtpd_need needs to be initialized with OSMTPD_NEED_RCPTTO. This attribute is a NULL-terminated array of address strings. If not available the first element in the array is set to NULL.

uint64_t evpid

The envelope ID we're currently working on. osmtpd_need needs to be initialized with OSMTPD_NEED_EVPID. If not available the attribute is set to 0.

void *local_session

Any filter specific data that needs to be stored during the session. This is initialized on ctx creation by calling oncreate argument from osmtpd_local_session.

void *local_message

Any filter specific data that needs to be stored during the message transaction. This is initialized on ctx creation by calling oncreate argument from osmtpd_local_message.

The osmtpd_register_filter class of functions must call one of osmtpd_filter_proceed, osmtpd_filter_rewrite, osmtpd_filter_reject and osmtpd_filter_disconnect. This can be done either in the callback function itself, or at a later moment through another callback. Note that the session stalls until the osmtpd_filter has been called.

Exceptions to the above reply options are:

•

osmtpd_register_filter_connect's and osmtpd_register_filter functions' callbacks without argument can't use osmtpd_filter_rewrite.

•

osmtpd_register_filter_dataline's callback can only use osmtpd_filter_dataline.

osmtpd_warn, osmtpd_warnx, osmtpd_err and osmtpd_errx can be used as a standin for warn(3) , warnx(3) , err(3) and errx(3) without printing the program name to stderr. Additionally, osmtpd_warn and osmtpd_warnx prints the request ID on the logline when ctx is not NULL.