1 2c1a20a1 2019-08-23 martijn .\" $OpenBSD$
3 6db83fcc 2019-08-22 martijn .\" Copyright (c) 2019 Martijn van Duren <martijn@openbsd.org>
5 6db83fcc 2019-08-22 martijn .\" Permission to use, copy, modify, and distribute this software for any
6 6db83fcc 2019-08-22 martijn .\" purpose with or without fee is hereby granted, provided that the above
7 6db83fcc 2019-08-22 martijn .\" copyright notice and this permission notice appear in all copies.
9 6db83fcc 2019-08-22 martijn .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 6db83fcc 2019-08-22 martijn .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 6db83fcc 2019-08-22 martijn .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 6db83fcc 2019-08-22 martijn .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 6db83fcc 2019-08-22 martijn .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 6db83fcc 2019-08-22 martijn .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 6db83fcc 2019-08-22 martijn .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 6db83fcc 2019-08-22 martijn .Dd $Mdocdate$
18 6db83fcc 2019-08-22 martijn .Dt OSMTPD_RUN 3
21 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_connect ,
22 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_helo ,
23 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_ehlo ,
24 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_starttls ,
25 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_auth ,
26 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_mailfrom ,
27 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_rcptto ,
28 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_data ,
29 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_dataline ,
30 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_rset ,
31 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_quit ,
32 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_noop ,
33 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_help ,
34 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_wiz ,
35 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_commit ,
36 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_connect ,
37 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_disconnect ,
38 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_identify ,
39 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_tls ,
40 58a6bc69 2022-12-05 martijn .Nm osmtpd_register_report_auth ,
41 d308c531 2025-02-03 martijn .Nm osmtpd_register_report_reset ,
42 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_begin ,
43 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_mail ,
44 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_rcpt ,
45 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_envelope ,
46 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_data ,
47 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_commit ,
48 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_rollback ,
49 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_client ,
50 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_server ,
51 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_response ,
52 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_timeout ,
53 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_session ,
54 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_message ,
55 6db83fcc 2019-08-22 martijn .Nm osmtpd_need ,
56 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_proceed ,
57 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_reject ,
58 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_disconnect ,
59 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_rewrite ,
60 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_dataline ,
61 2c1a20a1 2019-08-23 martijn .Nm osmtpd_run ,
62 2c1a20a1 2019-08-23 martijn .Nm osmtpd_err ,
63 9aeab972 2019-08-22 martijn .Nm osmtpd_errx
64 1a5c543c 2026-03-19 martijn .Nm osmtpd_warn ,
65 1a5c543c 2026-03-19 martijn .Nm osmtpd_warnx ,
66 1a5c543c 2026-03-19 martijn .Nm osmtpd_info ,
67 1a5c543c 2026-03-19 martijn .Nm osmtpd_debug ,
68 6db83fcc 2019-08-22 martijn .Nd C filter API for
69 6db83fcc 2019-08-22 martijn .Xr smtpd 8
70 6db83fcc 2019-08-22 martijn .Sh SYNOPSIS
71 e30dd692 2025-06-06 martijn .Lb libopensmtpd
72 6db83fcc 2019-08-22 martijn .In opensmtpd.h
74 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_connect
75 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *hostname, struct sockaddr_storage *ss)"
78 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_helo
79 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *helo)"
82 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_ehlo
83 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *ehlo)"
86 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_starttls
87 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
90 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_auth
91 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *auth)"
94 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_mailfrom
95 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *from)"
98 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_rcptto
99 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *rcpt)"
101 6db83fcc 2019-08-22 martijn .Ft void
102 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_data
103 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
105 6db83fcc 2019-08-22 martijn .Ft void
106 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_dataline
107 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *line)"
109 6db83fcc 2019-08-22 martijn .Ft void
110 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_rset
111 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
113 6db83fcc 2019-08-22 martijn .Ft void
114 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_quit
115 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
117 6db83fcc 2019-08-22 martijn .Ft void
118 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_noop
119 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
121 6db83fcc 2019-08-22 martijn .Ft void
122 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_help
123 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
125 6db83fcc 2019-08-22 martijn .Ft void
126 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_wiz
127 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
129 6db83fcc 2019-08-22 martijn .Ft void
130 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_commit
131 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
133 6db83fcc 2019-08-22 martijn .Ft void
134 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_connect
135 6db83fcc 2019-08-22 martijn .Fa "int incoming"
136 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *rdns, enum osmtpd_status fcrdns, struct sockaddr_storage *src, struct sockaddr_storage *dst)"
138 6db83fcc 2019-08-22 martijn .Ft void
139 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_disconnect
140 6db83fcc 2019-08-22 martijn .Fa "int incoming"
141 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
143 6db83fcc 2019-08-22 martijn .Ft void
144 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_identify
145 6db83fcc 2019-08-22 martijn .Fa "int incoming"
146 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *identity)"
148 6db83fcc 2019-08-22 martijn .Ft void
149 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_tls
150 6db83fcc 2019-08-22 martijn .Fa "int incoming"
151 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *ciphers)"
153 6db83fcc 2019-08-22 martijn .Ft void
154 58a6bc69 2022-12-05 martijn .Fo osmtpd_register_report_auth
155 58a6bc69 2022-12-05 martijn .Fa "int incoming"
156 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *username, enum osmtpd_auth_status status)"
158 58a6bc69 2022-12-05 martijn .Ft void
159 d308c531 2025-02-03 martijn .Fo osmtpd_register_report_reset
160 d308c531 2025-02-03 martijn .Fa "int incoming"
161 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid)"
163 d308c531 2025-02-03 martijn .Ft void
164 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_begin
165 6db83fcc 2019-08-22 martijn .Fa "int incoming"
166 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid)"
168 6db83fcc 2019-08-22 martijn .Ft void
169 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_mail
170 6db83fcc 2019-08-22 martijn .Fa "int incoming"
171 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, const char *mailfrom, enum osmtpd_status status)"
173 6db83fcc 2019-08-22 martijn .Ft void
174 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_rcpt
175 6db83fcc 2019-08-22 martijn .Fa "int incoming"
176 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, const char *rcptto, enum osmtpd_status status)"
178 6db83fcc 2019-08-22 martijn .Ft void
179 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_envelope
180 6db83fcc 2019-08-22 martijn .Fa "int incoming"
181 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, uint64_t evpid)"
183 6db83fcc 2019-08-22 martijn .Ft void
184 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_data
185 6db83fcc 2019-08-22 martijn .Fa "int incoming"
186 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, enum osmtpd_status status)"
188 6db83fcc 2019-08-22 martijn .Ft void
189 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_commit
190 6db83fcc 2019-08-22 martijn .Fa int incoming
191 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, size_t msgsz)"
193 6db83fcc 2019-08-22 martijn .Ft void
194 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_rollback
195 6db83fcc 2019-08-22 martijn .Fa "int incoming"
196 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid)"
198 6db83fcc 2019-08-22 martijn .Ft void
199 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_client
200 6db83fcc 2019-08-22 martijn .Fa "int incoming"
201 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *cmd)"
203 6db83fcc 2019-08-22 martijn .Ft void
204 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_server
205 6db83fcc 2019-08-22 martijn .Fa "int incoming"
206 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *resp)"
208 6db83fcc 2019-08-22 martijn .Ft void
209 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_response
210 6db83fcc 2019-08-22 martijn .Fa "int incoming"
211 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *resp)"
213 6db83fcc 2019-08-22 martijn .Ft void
214 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_timeout
215 6db83fcc 2019-08-22 martijn .Fa "int incoming"
216 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
218 6db83fcc 2019-08-22 martijn .Ft void
219 6db83fcc 2019-08-22 martijn .Fo osmtpd_local_session
220 6db83fcc 2019-08-22 martijn .Fa "void *(*oncreate)(struct osmtpd_ctx *ctx)"
221 6db83fcc 2019-08-22 martijn .Fa "void (*ondelete)(struct osmtpd_ctx *ctx, void *data)"
223 6db83fcc 2019-08-22 martijn .Ft void
224 6db83fcc 2019-08-22 martijn .Fo osmtpd_local_message
225 6db83fcc 2019-08-22 martijn .Fa "void *(*oncreate)(struct osmtpd_ctx *ctx)"
226 6db83fcc 2019-08-22 martijn .Fa "void (*ondelete)(struct osmtpd_ctx *ctx, void *data)"
228 6db83fcc 2019-08-22 martijn .Ft void
229 6db83fcc 2019-08-22 martijn .Fn osmtpd_need "int needs"
230 6db83fcc 2019-08-22 martijn .Ft void
231 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_proceed "struct osmtpd_ctx *ctx"
232 6db83fcc 2019-08-22 martijn .Ft void
233 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_reject "struct osmtpd_ctx *ctx" "int error" "const char *msg" ...
234 6db83fcc 2019-08-22 martijn .Ft void
235 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_disconnect "struct osmtpd_ctx *ctx" "const char *msg" ...
236 6db83fcc 2019-08-22 martijn .Ft void
237 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_rewrite "struct osmtpd_ctx *ctx" "const char *value" ...
238 6db83fcc 2019-08-22 martijn .Ft void
239 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_dataline "struct osmtpd_ctx *ctx" "const char *line" ...
240 6db83fcc 2019-08-22 martijn .Ft void
241 6db83fcc 2019-08-22 martijn .Fn osmtpd_run void
242 9aeab972 2019-08-22 martijn .Ft void
243 9aeab972 2019-08-22 martijn .Fn osmtpd_err "int eval" "const char *fmt" ...
244 9aeab972 2019-08-22 martijn .Ft void
245 9aeab972 2019-08-22 martijn .Fn osmtpd_errx "int eval" "const char *fmt" ...
246 1a5c543c 2026-03-19 martijn .Ft void
247 1a5c543c 2026-03-19 martijn .Fn osmtpd_warn "struct osmtpd_ctx *ctx" "const char *fmt" ...
248 1a5c543c 2026-03-19 martijn .Ft void
249 1a5c543c 2026-03-19 martijn .Fn osmtpd_warnx "struct osmtpd_ctx *ctx" "const char *fmt" ...
250 1a5c543c 2026-03-19 martijn .Ft void
251 1a5c543c 2026-03-19 martijn .Fn osmtpd_info "struct osmtpd_ctx *ctx" "const char *fmt" ...
252 1a5c543c 2026-03-19 martijn .Ft void
253 1a5c543c 2026-03-19 martijn .Fn osmtpd_debug "struct osmtpd_ctx *ctx" "const char *fmt" ...
254 6db83fcc 2019-08-22 martijn .Sh DESCRIPTION
256 6db83fcc 2019-08-22 martijn .Nm osmtpd
257 6db83fcc 2019-08-22 martijn API is an event based interface for writing
258 6db83fcc 2019-08-22 martijn .Xr smtpd 8
259 6db83fcc 2019-08-22 martijn filters.
260 6db83fcc 2019-08-22 martijn Filter and report callbacks are registered via the
261 6db83fcc 2019-08-22 martijn .Nm osmtpd_register
262 6db83fcc 2019-08-22 martijn class of functions, followed by
263 6db83fcc 2019-08-22 martijn .Nm osmtpd_run .
264 5129e9c0 2025-04-10 kirill A callback should return
266 5129e9c0 2025-04-10 kirill in the case of success, or
268 5129e9c0 2025-04-10 kirill in the case of error which leads to disconnect of this session.
270 6db83fcc 2019-08-22 martijn .Nm osmtpd_run
271 2c1a20a1 2019-08-23 martijn starts the communication with the server and transforms network queries to
272 6db83fcc 2019-08-22 martijn callbacks.
273 6db83fcc 2019-08-22 martijn Internally it uses
274 6db83fcc 2019-08-22 martijn .Xr event_dispatch 3 ,
275 6db83fcc 2019-08-22 martijn which allows filters to be written fully asynchronously.
277 6db83fcc 2019-08-22 martijn Each callback
279 6db83fcc 2019-08-22 martijn gets at least a pointer of the type
280 2c1a20a1 2019-08-23 martijn .Fa struct osmtpd_ctx .
281 6db83fcc 2019-08-22 martijn It contains the following elements:
282 2c1a20a1 2019-08-23 martijn .Bl -tag -width Ds
283 6db83fcc 2019-08-22 martijn .It Fa "enum osmtpd_type type"
284 6db83fcc 2019-08-22 martijn The type of request being made.
285 2c1a20a1 2019-08-23 martijn The possible values are
286 6db83fcc 2019-08-22 martijn .Dv OSMTPD_TYPE_FILTER
288 6db83fcc 2019-08-22 martijn .Dv OSMTPD_TYPE_REPORT .
289 6db83fcc 2019-08-22 martijn .It Vt "enum osmtpd_phase" Va phase
290 6db83fcc 2019-08-22 martijn The phase in the transaction which triggered the callback.
291 6db83fcc 2019-08-22 martijn The following values match their respective
292 6db83fcc 2019-08-22 martijn .Nm osmtpd_register
293 6db83fcc 2019-08-22 martijn function:
294 6db83fcc 2019-08-22 martijn .Bl -tag -compact -width OSMTPD_PHASE_LINK_DISCONNECT
295 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_CONNECT
296 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_connect
297 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_HELO
298 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_helo
299 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_EHLO
300 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_ehlo
301 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_STARTTLS
302 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_starttls
303 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_AUTH
304 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_auth
305 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_MAIL_FROM
306 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_mailfrom
307 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_RCPT_TO
308 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_rcptto
309 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_DATA
310 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_data
311 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_DATA_LINE
312 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_dataline
313 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_RSET
314 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_rset
315 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_QUIT
316 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_quit
317 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_NOOP
318 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_noop
319 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_HELP
320 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_help
321 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_WIZ
322 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_wiz
323 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_COMMIT
324 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_commit
325 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_LINK_CONNECT
326 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_connect
327 6db83fcc 2019-08-22 martijn .It OSMTPD_PHASE_LINK_DISCONNECT
328 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_disconnect
329 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_LINK_IDENTIFY
330 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_identify
331 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_LINK_TLS
332 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_tls
333 58a6bc69 2022-12-05 martijn .It Dv OSMTPD_PHASE_LINK_AUTH
334 58a6bc69 2022-12-05 martijn .Nm osmtpd_register_report_auth
335 d308c531 2025-02-03 martijn .It Dv OSMTPD_PHASE_TX_RESET
336 d308c531 2025-02-03 martijn .Nm osmtpd_register_report_reset
337 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_BEGIN
338 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_begin
339 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_MAIL
340 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_mail
341 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_RCPT
342 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_rcpt
343 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_ENVELOPE
344 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_envelope
345 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_DATA
346 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_data
347 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_COMMIT
348 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_commit
349 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_ROLLBACK
350 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_rollback
351 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_PROTOCOL_CLIENT
352 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_client
353 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_PROTOCOL_SERVER
354 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_server
355 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_FILTER_RESPONSE
356 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_response
357 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TIMEOUT .
358 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_timeout
360 6db83fcc 2019-08-22 martijn .It Vt int Va version_major
361 6db83fcc 2019-08-22 martijn The major version number of the protocol.
362 6db83fcc 2019-08-22 martijn Most filters don't need this information.
363 6db83fcc 2019-08-22 martijn .It Vt int Va version_minor
364 6db83fcc 2019-08-22 martijn The minor version number of the protocol.
365 6db83fcc 2019-08-22 martijn Most filters don't need this information.
366 6db83fcc 2019-08-22 martijn .It Vt "struct timespec" Va tm
367 6db83fcc 2019-08-22 martijn The time the event was triggered inside
368 6db83fcc 2019-08-22 martijn .Xr smtpd 8 .
369 6db83fcc 2019-08-22 martijn .It Vt int Va incoming
370 2cae084d 2021-04-18 martijn Set to 1 if the event was based on an incoming connection, 0 if it's an outgoing
371 2c1a20a1 2019-08-23 martijn connection.
373 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter
374 6db83fcc 2019-08-22 martijn class of functions is always based on incoming connections.
375 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report
376 6db83fcc 2019-08-22 martijn can be both incoming and outgoing.
377 6db83fcc 2019-08-22 martijn .It Vt uint64_t Va reqid
378 2c1a20a1 2019-08-23 martijn The request ID of the connection the event was issued on.
379 6db83fcc 2019-08-22 martijn This value can be useful for logging.
380 6db83fcc 2019-08-22 martijn Filters in need of filter specific data can use
381 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_session
383 6db83fcc 2019-08-22 martijn .Va local_session .
384 6db83fcc 2019-08-22 martijn .It Vt uint64_t Va token
385 6db83fcc 2019-08-22 martijn The filter specific token.
386 6db83fcc 2019-08-22 martijn Most filters don't need this information.
387 6db83fcc 2019-08-22 martijn .It Vt "struct sockaddr_storage" Va src
388 6db83fcc 2019-08-22 martijn The source address and port of the connection.
389 6db83fcc 2019-08-22 martijn This needs to be cast to the appropriate sockaddr type based on the
390 6db83fcc 2019-08-22 martijn .Va ss_family
391 6db83fcc 2019-08-22 martijn attribute.
392 6db83fcc 2019-08-22 martijn It can have the following families:
393 6db83fcc 2019-08-22 martijn .Dv AF_INET ,
394 6db83fcc 2019-08-22 martijn .Dv AF_INET6
396 6db83fcc 2019-08-22 martijn .Dv AF_UNIX .
397 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
398 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
400 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_SRC .
401 6db83fcc 2019-08-22 martijn If not available the entire attribute is zeroed out.
402 6db83fcc 2019-08-22 martijn .It Vt "struct sockaddr_storage" Va dst
403 6db83fcc 2019-08-22 martijn The destination address and port of the connection.
404 6db83fcc 2019-08-22 martijn This needs to be cast to the appropriate sockaddr type based on the
405 6db83fcc 2019-08-22 martijn .Va ss_family
406 6db83fcc 2019-08-22 martijn attribute.
407 6db83fcc 2019-08-22 martijn It can have the following families:
408 6db83fcc 2019-08-22 martijn .Dv AF_INET ,
409 6db83fcc 2019-08-22 martijn .Dv AF_INET6
411 6db83fcc 2019-08-22 martijn .Dv AF_UNIX .
412 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
413 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
415 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_DST .
416 6db83fcc 2019-08-22 martijn If not available the entire attribute is zeroed out.
417 6db83fcc 2019-08-22 martijn .It Vt char Va *rdns
418 6db83fcc 2019-08-22 martijn The reverse DNS hostname of the connection.
419 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
420 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
422 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_RDNS .
423 6db83fcc 2019-08-22 martijn If not available the attribute is set to
424 6db83fcc 2019-08-22 martijn .Dv NULL .
425 30f1cbac 2019-08-22 martijn .It Vt enum osmtpd_status Va fcrdns
426 30f1cbac 2019-08-22 martijn Whether the reverse DNS hostname is forward confirmed.
427 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
428 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
430 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_FCRDNS .
431 6db83fcc 2019-08-22 martijn If not available the attribute is set to
432 30f1cbac 2019-08-22 martijn .Dv OSMTPD_STATUS_TEMPFAIL .
433 6db83fcc 2019-08-22 martijn .It Vt char Va *identity
434 2c1a20a1 2019-08-23 martijn The identity of the remote host as presented by the HELO or EHLO SMTP command.
435 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
436 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
438 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_IDENTITY .
439 6db83fcc 2019-08-22 martijn If not available the attribute is set to
440 6db83fcc 2019-08-22 martijn .Dv NULL .
441 6db83fcc 2019-08-22 martijn .It Vt char Va *ciphers
442 6db83fcc 2019-08-22 martijn The ciphers used during
443 6db83fcc 2019-08-22 martijn .Po start Pc Ns tls .
444 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
445 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
447 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_CIPHERS .
448 6db83fcc 2019-08-22 martijn If not available the attribute is set to
449 6db83fcc 2019-08-22 martijn .Dv NULL .
450 6db83fcc 2019-08-22 martijn .It Vt uint32_t Va msgid
451 2c1a20a1 2019-08-23 martijn The message ID of the current message being handled in the SMTP transaction.
452 6db83fcc 2019-08-22 martijn This value can be useful for logging.
453 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
454 6db83fcc 2019-08-22 martijn needs to be initialized with
455 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_MSGID .
456 6db83fcc 2019-08-22 martijn If not available the attribute is set to
458 6db83fcc 2019-08-22 martijn Filters in need of filter specific data can use
459 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_message
461 6db83fcc 2019-08-22 martijn .Va local_message .
462 58a6bc69 2022-12-05 martijn .It Vt char Va *username
463 58a6bc69 2022-12-05 martijn The username with which the session was successfully authenticated.
464 58a6bc69 2022-12-05 martijn .Nm osmtpd_need
465 58a6bc69 2022-12-05 martijn needs to be initialized with
466 58a6bc69 2022-12-05 martijn .DV OSMTPD_NEED_USERNAME .
467 58a6bc69 2022-12-05 martijn If not available or authentication failed is set to
468 58a6bc69 2022-12-05 martijn .Dv NULL .
469 6db83fcc 2019-08-22 martijn .It Vt char Va *mailfrom
470 2c1a20a1 2019-08-23 martijn The envelope MAIL FROM address in the SMTP transaction.
471 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
472 6db83fcc 2019-08-22 martijn needs to be initialized with
473 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_MAILFROM .
474 6db83fcc 2019-08-22 martijn If not available the attribute is set to
475 6db83fcc 2019-08-22 martijn .Dv NULL .
476 6db83fcc 2019-08-22 martijn .It Vt char Va **rcptto
477 2c1a20a1 2019-08-23 martijn The envelope RCPT TO address in the SMTP transaction.
478 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
479 6db83fcc 2019-08-22 martijn needs to be initialized with
480 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_RCPTTO .
481 6db83fcc 2019-08-22 martijn This attribute is a NULL-terminated array of address strings.
482 6db83fcc 2019-08-22 martijn If not available the first element in the array is set to
483 6db83fcc 2019-08-22 martijn .Dv NULL .
484 2c1a20a1 2019-08-23 martijn .It Vt uint64_t Va evpid
485 2c1a20a1 2019-08-23 martijn The envelope ID we're currently working on.
486 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
487 6db83fcc 2019-08-22 martijn needs to be initialized with
488 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_EVPID .
489 6db83fcc 2019-08-22 martijn If not available the attribute is set to
491 2c1a20a1 2019-08-23 martijn .It Vt void Va *local_session
492 6db83fcc 2019-08-22 martijn Any filter specific data that needs to be stored during the session.
493 6db83fcc 2019-08-22 martijn This is initialized on
495 6db83fcc 2019-08-22 martijn creation by calling
496 6db83fcc 2019-08-22 martijn .Fa oncreate
497 6db83fcc 2019-08-22 martijn argument from
498 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_session .
499 2c1a20a1 2019-08-23 martijn .It Vt void Va *local_message
500 6db83fcc 2019-08-22 martijn Any filter specific data that needs to be stored during the message transaction.
501 6db83fcc 2019-08-22 martijn This is initialized on
503 6db83fcc 2019-08-22 martijn creation by calling
504 6db83fcc 2019-08-22 martijn .Fa oncreate
505 6db83fcc 2019-08-22 martijn argument from
506 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_message .
510 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter
511 6db83fcc 2019-08-22 martijn class of functions must call one of
512 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_proceed ,
513 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_rewrite ,
514 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_reject
516 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_disconnect .
517 6db83fcc 2019-08-22 martijn This can be done either in the callback function itself, or at a later moment
518 6db83fcc 2019-08-22 martijn through another callback.
519 6db83fcc 2019-08-22 martijn Note that the session stalls until the
520 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter
521 6db83fcc 2019-08-22 martijn has been called.
523 6db83fcc 2019-08-22 martijn Exceptions to the above reply options are:
525 6db83fcc 2019-08-22 martijn .Bl -bullet -compact -width Ds
527 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_connect Ns 's
529 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter
530 6db83fcc 2019-08-22 martijn functions' callbacks without argument can't use
531 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_rewrite .
533 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_dataline Ns 's
534 6db83fcc 2019-08-22 martijn callback can only use osmtpd_filter_dataline.
537 1a5c543c 2026-03-19 martijn .Nm osmtpd_err ,
538 1a5c543c 2026-03-19 martijn .Nm osmtpd_errx ,
539 8b9e9928 2025-01-30 kirill .Nm osmtpd_warn ,
540 8b9e9928 2025-01-30 kirill .Nm osmtpd_warnx ,
541 1a5c543c 2026-03-19 martijn .Nm osmtpd_info ,
543 1a5c543c 2026-03-19 martijn .Nm osmtpd_debug
544 1a5c543c 2026-03-19 martijn are used for logging to
545 1a5c543c 2026-03-19 martijn .Xr smtpd 8
547 1a5c543c 2026-03-19 martijn .Xr syslog 3
549 1a5c543c 2026-03-19 martijn .Dv LOG_CRIT ,
550 1a5c543c 2026-03-19 martijn .Dv LOG_WARNING ,
551 1a5c543c 2026-03-19 martijn .Dv LOG_INFO,
553 1a5c543c 2026-03-19 martijn .Dv LOG_DEBUG
554 1a5c543c 2026-03-19 martijn respectively.
555 8b9e9928 2025-01-30 kirill Additionally,
556 1a5c543c 2026-03-19 martijn .Nm osmtpd_warn ,
557 1a5c543c 2026-03-19 martijn .Nm osmtpd_warnx ,
558 1a5c543c 2026-03-19 martijn .Nm osmtpd_info ,
560 1a5c543c 2026-03-19 martijn .Nm osmtpd_debug
561 8b9e9928 2025-01-30 kirill prints the request ID on the logline when
564 8b9e9928 2025-01-30 kirill .Dv NULL .
565 6db83fcc 2019-08-22 martijn .Sh SEE ALSO
566 6db83fcc 2019-08-22 martijn .Xr event_init 3 ,
567 6db83fcc 2019-08-22 martijn .Xr smtpd.conf 5
568 6db83fcc 2019-08-22 martijn .Sh HISTORY
570 6db83fcc 2019-08-22 martijn .Nm osmtpd_run
571 6db83fcc 2019-08-22 martijn API first appeared in
572 6db83fcc 2019-08-22 martijn .Ox 6.6 .
573 6db83fcc 2019-08-22 martijn .Sh AUTHORS
574 6db83fcc 2019-08-22 martijn .An Martijn van Duren Aq Mt martijn@openbsd.org
