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 8b9e9928 2025-01-30 kirill .Nm osmtpd_warn ,
63 8b9e9928 2025-01-30 kirill .Nm osmtpd_warnx ,
64 2c1a20a1 2019-08-23 martijn .Nm osmtpd_err ,
65 9aeab972 2019-08-22 martijn .Nm osmtpd_errx
66 6db83fcc 2019-08-22 martijn .Nd C filter API for
67 6db83fcc 2019-08-22 martijn .Xr smtpd 8
68 6db83fcc 2019-08-22 martijn .Sh SYNOPSIS
69 e30dd692 2025-06-06 martijn .Lb libopensmtpd
70 6db83fcc 2019-08-22 martijn .In opensmtpd.h
72 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_connect
73 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *hostname, struct sockaddr_storage *ss)"
76 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_helo
77 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *helo)"
80 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_ehlo
81 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *ehlo)"
84 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_starttls
85 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
88 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_auth
89 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *auth)"
92 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_mailfrom
93 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *from)"
96 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_rcptto
97 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *rcpt)"
100 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_data
101 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
103 6db83fcc 2019-08-22 martijn .Ft void
104 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_dataline
105 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *line)"
107 6db83fcc 2019-08-22 martijn .Ft void
108 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_rset
109 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
111 6db83fcc 2019-08-22 martijn .Ft void
112 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_quit
113 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
115 6db83fcc 2019-08-22 martijn .Ft void
116 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_noop
117 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
119 6db83fcc 2019-08-22 martijn .Ft void
120 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_help
121 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
123 6db83fcc 2019-08-22 martijn .Ft void
124 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_wiz
125 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
127 6db83fcc 2019-08-22 martijn .Ft void
128 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_filter_commit
129 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
131 6db83fcc 2019-08-22 martijn .Ft void
132 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_connect
133 6db83fcc 2019-08-22 martijn .Fa "int incoming"
134 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)"
136 6db83fcc 2019-08-22 martijn .Ft void
137 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_disconnect
138 6db83fcc 2019-08-22 martijn .Fa "int incoming"
139 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
141 6db83fcc 2019-08-22 martijn .Ft void
142 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_identify
143 6db83fcc 2019-08-22 martijn .Fa "int incoming"
144 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *identity)"
146 6db83fcc 2019-08-22 martijn .Ft void
147 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_tls
148 6db83fcc 2019-08-22 martijn .Fa "int incoming"
149 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *ciphers)"
151 6db83fcc 2019-08-22 martijn .Ft void
152 58a6bc69 2022-12-05 martijn .Fo osmtpd_register_report_auth
153 58a6bc69 2022-12-05 martijn .Fa "int incoming"
154 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *username, enum osmtpd_auth_status status)"
156 58a6bc69 2022-12-05 martijn .Ft void
157 d308c531 2025-02-03 martijn .Fo osmtpd_register_report_reset
158 d308c531 2025-02-03 martijn .Fa "int incoming"
159 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid)"
161 d308c531 2025-02-03 martijn .Ft void
162 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_begin
163 6db83fcc 2019-08-22 martijn .Fa "int incoming"
164 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid)"
166 6db83fcc 2019-08-22 martijn .Ft void
167 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_mail
168 6db83fcc 2019-08-22 martijn .Fa "int incoming"
169 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, const char *mailfrom, enum osmtpd_status status)"
171 6db83fcc 2019-08-22 martijn .Ft void
172 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_rcpt
173 6db83fcc 2019-08-22 martijn .Fa "int incoming"
174 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, const char *rcptto, enum osmtpd_status status)"
176 6db83fcc 2019-08-22 martijn .Ft void
177 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_envelope
178 6db83fcc 2019-08-22 martijn .Fa "int incoming"
179 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, uint64_t evpid)"
181 6db83fcc 2019-08-22 martijn .Ft void
182 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_data
183 6db83fcc 2019-08-22 martijn .Fa "int incoming"
184 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, enum osmtpd_status status)"
186 6db83fcc 2019-08-22 martijn .Ft void
187 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_commit
188 6db83fcc 2019-08-22 martijn .Fa int incoming
189 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid, size_t msgsz)"
191 6db83fcc 2019-08-22 martijn .Ft void
192 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_rollback
193 6db83fcc 2019-08-22 martijn .Fa "int incoming"
194 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, uint32_t msgid)"
196 6db83fcc 2019-08-22 martijn .Ft void
197 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_client
198 6db83fcc 2019-08-22 martijn .Fa "int incoming"
199 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *cmd)"
201 6db83fcc 2019-08-22 martijn .Ft void
202 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_server
203 6db83fcc 2019-08-22 martijn .Fa "int incoming"
204 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *resp)"
206 6db83fcc 2019-08-22 martijn .Ft void
207 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_response
208 6db83fcc 2019-08-22 martijn .Fa "int incoming"
209 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx, const char *resp)"
211 6db83fcc 2019-08-22 martijn .Ft void
212 6db83fcc 2019-08-22 martijn .Fo osmtpd_register_report_timeout
213 6db83fcc 2019-08-22 martijn .Fa "int incoming"
214 5129e9c0 2025-04-10 kirill .Fa "int (*cb)(struct osmtpd_ctx *ctx)"
216 6db83fcc 2019-08-22 martijn .Ft void
217 6db83fcc 2019-08-22 martijn .Fo osmtpd_local_session
218 6db83fcc 2019-08-22 martijn .Fa "void *(*oncreate)(struct osmtpd_ctx *ctx)"
219 6db83fcc 2019-08-22 martijn .Fa "void (*ondelete)(struct osmtpd_ctx *ctx, void *data)"
221 6db83fcc 2019-08-22 martijn .Ft void
222 6db83fcc 2019-08-22 martijn .Fo osmtpd_local_message
223 6db83fcc 2019-08-22 martijn .Fa "void *(*oncreate)(struct osmtpd_ctx *ctx)"
224 6db83fcc 2019-08-22 martijn .Fa "void (*ondelete)(struct osmtpd_ctx *ctx, void *data)"
226 6db83fcc 2019-08-22 martijn .Ft void
227 6db83fcc 2019-08-22 martijn .Fn osmtpd_need "int needs"
228 6db83fcc 2019-08-22 martijn .Ft void
229 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_proceed "struct osmtpd_ctx *ctx"
230 6db83fcc 2019-08-22 martijn .Ft void
231 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_reject "struct osmtpd_ctx *ctx" "int error" "const char *msg" ...
232 6db83fcc 2019-08-22 martijn .Ft void
233 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_disconnect "struct osmtpd_ctx *ctx" "const char *msg" ...
234 6db83fcc 2019-08-22 martijn .Ft void
235 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_rewrite "struct osmtpd_ctx *ctx" "const char *value" ...
236 6db83fcc 2019-08-22 martijn .Ft void
237 6db83fcc 2019-08-22 martijn .Fn osmtpd_filter_dataline "struct osmtpd_ctx *ctx" "const char *line" ...
238 6db83fcc 2019-08-22 martijn .Ft void
239 6db83fcc 2019-08-22 martijn .Fn osmtpd_run void
240 9aeab972 2019-08-22 martijn .Ft void
241 8b9e9928 2025-01-30 kirill .Fn osmtpd_warn "struct osmtpd_ctx *ctx" "const char *fmt" ...
243 8b9e9928 2025-01-30 kirill .Fn osmtpd_warnx "struct osmtpd_ctx *ctx" "const char *fmt" ...
245 9aeab972 2019-08-22 martijn .Fn osmtpd_err "int eval" "const char *fmt" ...
246 9aeab972 2019-08-22 martijn .Ft void
247 9aeab972 2019-08-22 martijn .Fn osmtpd_errx "int eval" "const char *fmt" ...
248 6db83fcc 2019-08-22 martijn .Sh DESCRIPTION
250 6db83fcc 2019-08-22 martijn .Nm osmtpd
251 6db83fcc 2019-08-22 martijn API is an event based interface for writing
252 6db83fcc 2019-08-22 martijn .Xr smtpd 8
253 6db83fcc 2019-08-22 martijn filters.
254 6db83fcc 2019-08-22 martijn Filter and report callbacks are registered via the
255 6db83fcc 2019-08-22 martijn .Nm osmtpd_register
256 6db83fcc 2019-08-22 martijn class of functions, followed by
257 6db83fcc 2019-08-22 martijn .Nm osmtpd_run .
258 5129e9c0 2025-04-10 kirill A callback should return
260 5129e9c0 2025-04-10 kirill in the case of success, or
262 5129e9c0 2025-04-10 kirill in the case of error which leads to disconnect of this session.
264 6db83fcc 2019-08-22 martijn .Nm osmtpd_run
265 2c1a20a1 2019-08-23 martijn starts the communication with the server and transforms network queries to
266 6db83fcc 2019-08-22 martijn callbacks.
267 6db83fcc 2019-08-22 martijn Internally it uses
268 6db83fcc 2019-08-22 martijn .Xr event_dispatch 3 ,
269 6db83fcc 2019-08-22 martijn which allows filters to be written fully asynchronously.
271 6db83fcc 2019-08-22 martijn Each callback
273 6db83fcc 2019-08-22 martijn gets at least a pointer of the type
274 2c1a20a1 2019-08-23 martijn .Fa struct osmtpd_ctx .
275 6db83fcc 2019-08-22 martijn It contains the following elements:
276 2c1a20a1 2019-08-23 martijn .Bl -tag -width Ds
277 6db83fcc 2019-08-22 martijn .It Fa "enum osmtpd_type type"
278 6db83fcc 2019-08-22 martijn The type of request being made.
279 2c1a20a1 2019-08-23 martijn The possible values are
280 6db83fcc 2019-08-22 martijn .Dv OSMTPD_TYPE_FILTER
282 6db83fcc 2019-08-22 martijn .Dv OSMTPD_TYPE_REPORT .
283 6db83fcc 2019-08-22 martijn .It Vt "enum osmtpd_phase" Va phase
284 6db83fcc 2019-08-22 martijn The phase in the transaction which triggered the callback.
285 6db83fcc 2019-08-22 martijn The following values match their respective
286 6db83fcc 2019-08-22 martijn .Nm osmtpd_register
287 6db83fcc 2019-08-22 martijn function:
288 6db83fcc 2019-08-22 martijn .Bl -tag -compact -width OSMTPD_PHASE_LINK_DISCONNECT
289 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_CONNECT
290 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_connect
291 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_HELO
292 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_helo
293 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_EHLO
294 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_ehlo
295 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_STARTTLS
296 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_starttls
297 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_AUTH
298 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_auth
299 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_MAIL_FROM
300 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_mailfrom
301 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_RCPT_TO
302 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_rcptto
303 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_DATA
304 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_data
305 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_DATA_LINE
306 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_dataline
307 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_RSET
308 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_rset
309 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_QUIT
310 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_quit
311 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_NOOP
312 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_noop
313 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_HELP
314 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_help
315 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_WIZ
316 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_wiz
317 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_COMMIT
318 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_commit
319 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_LINK_CONNECT
320 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_connect
321 6db83fcc 2019-08-22 martijn .It OSMTPD_PHASE_LINK_DISCONNECT
322 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_disconnect
323 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_LINK_IDENTIFY
324 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_identify
325 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_LINK_TLS
326 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_tls
327 58a6bc69 2022-12-05 martijn .It Dv OSMTPD_PHASE_LINK_AUTH
328 58a6bc69 2022-12-05 martijn .Nm osmtpd_register_report_auth
329 d308c531 2025-02-03 martijn .It Dv OSMTPD_PHASE_TX_RESET
330 d308c531 2025-02-03 martijn .Nm osmtpd_register_report_reset
331 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_BEGIN
332 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_begin
333 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_MAIL
334 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_mail
335 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_RCPT
336 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_rcpt
337 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_ENVELOPE
338 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_envelope
339 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_DATA
340 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_data
341 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_COMMIT
342 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_commit
343 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TX_ROLLBACK
344 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_rollback
345 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_PROTOCOL_CLIENT
346 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_client
347 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_PROTOCOL_SERVER
348 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_server
349 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_FILTER_RESPONSE
350 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_response
351 6db83fcc 2019-08-22 martijn .It Dv OSMTPD_PHASE_TIMEOUT .
352 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report_timeout
354 6db83fcc 2019-08-22 martijn .It Vt int Va version_major
355 6db83fcc 2019-08-22 martijn The major version number of the protocol.
356 6db83fcc 2019-08-22 martijn Most filters don't need this information.
357 6db83fcc 2019-08-22 martijn .It Vt int Va version_minor
358 6db83fcc 2019-08-22 martijn The minor version number of the protocol.
359 6db83fcc 2019-08-22 martijn Most filters don't need this information.
360 6db83fcc 2019-08-22 martijn .It Vt "struct timespec" Va tm
361 6db83fcc 2019-08-22 martijn The time the event was triggered inside
362 6db83fcc 2019-08-22 martijn .Xr smtpd 8 .
363 6db83fcc 2019-08-22 martijn .It Vt int Va incoming
364 2cae084d 2021-04-18 martijn Set to 1 if the event was based on an incoming connection, 0 if it's an outgoing
365 2c1a20a1 2019-08-23 martijn connection.
367 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter
368 6db83fcc 2019-08-22 martijn class of functions is always based on incoming connections.
369 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_report
370 6db83fcc 2019-08-22 martijn can be both incoming and outgoing.
371 6db83fcc 2019-08-22 martijn .It Vt uint64_t Va reqid
372 2c1a20a1 2019-08-23 martijn The request ID of the connection the event was issued on.
373 6db83fcc 2019-08-22 martijn This value can be useful for logging.
374 6db83fcc 2019-08-22 martijn Filters in need of filter specific data can use
375 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_session
377 6db83fcc 2019-08-22 martijn .Va local_session .
378 6db83fcc 2019-08-22 martijn .It Vt uint64_t Va token
379 6db83fcc 2019-08-22 martijn The filter specific token.
380 6db83fcc 2019-08-22 martijn Most filters don't need this information.
381 6db83fcc 2019-08-22 martijn .It Vt "struct sockaddr_storage" Va src
382 6db83fcc 2019-08-22 martijn The source address and port of the connection.
383 6db83fcc 2019-08-22 martijn This needs to be cast to the appropriate sockaddr type based on the
384 6db83fcc 2019-08-22 martijn .Va ss_family
385 6db83fcc 2019-08-22 martijn attribute.
386 6db83fcc 2019-08-22 martijn It can have the following families:
387 6db83fcc 2019-08-22 martijn .Dv AF_INET ,
388 6db83fcc 2019-08-22 martijn .Dv AF_INET6
390 6db83fcc 2019-08-22 martijn .Dv AF_UNIX .
391 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
392 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
394 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_SRC .
395 6db83fcc 2019-08-22 martijn If not available the entire attribute is zeroed out.
396 6db83fcc 2019-08-22 martijn .It Vt "struct sockaddr_storage" Va dst
397 6db83fcc 2019-08-22 martijn The destination address and port of the connection.
398 6db83fcc 2019-08-22 martijn This needs to be cast to the appropriate sockaddr type based on the
399 6db83fcc 2019-08-22 martijn .Va ss_family
400 6db83fcc 2019-08-22 martijn attribute.
401 6db83fcc 2019-08-22 martijn It can have the following families:
402 6db83fcc 2019-08-22 martijn .Dv AF_INET ,
403 6db83fcc 2019-08-22 martijn .Dv AF_INET6
405 6db83fcc 2019-08-22 martijn .Dv AF_UNIX .
406 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
407 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
409 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_DST .
410 6db83fcc 2019-08-22 martijn If not available the entire attribute is zeroed out.
411 6db83fcc 2019-08-22 martijn .It Vt char Va *rdns
412 6db83fcc 2019-08-22 martijn The reverse DNS hostname of the connection.
413 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
414 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
416 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_RDNS .
417 6db83fcc 2019-08-22 martijn If not available the attribute is set to
418 6db83fcc 2019-08-22 martijn .Dv NULL .
419 30f1cbac 2019-08-22 martijn .It Vt enum osmtpd_status Va fcrdns
420 30f1cbac 2019-08-22 martijn Whether the reverse DNS hostname is forward confirmed.
421 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
422 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
424 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_FCRDNS .
425 6db83fcc 2019-08-22 martijn If not available the attribute is set to
426 30f1cbac 2019-08-22 martijn .Dv OSMTPD_STATUS_TEMPFAIL .
427 6db83fcc 2019-08-22 martijn .It Vt char Va *identity
428 2c1a20a1 2019-08-23 martijn The identity of the remote host as presented by the HELO or EHLO SMTP command.
429 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
430 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
432 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_IDENTITY .
433 6db83fcc 2019-08-22 martijn If not available the attribute is set to
434 6db83fcc 2019-08-22 martijn .Dv NULL .
435 6db83fcc 2019-08-22 martijn .It Vt char Va *ciphers
436 6db83fcc 2019-08-22 martijn The ciphers used during
437 6db83fcc 2019-08-22 martijn .Po start Pc Ns tls .
438 2c1a20a1 2019-08-23 martijn To use this attribute, initialize
439 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
441 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_CIPHERS .
442 6db83fcc 2019-08-22 martijn If not available the attribute is set to
443 6db83fcc 2019-08-22 martijn .Dv NULL .
444 6db83fcc 2019-08-22 martijn .It Vt uint32_t Va msgid
445 2c1a20a1 2019-08-23 martijn The message ID of the current message being handled in the SMTP transaction.
446 6db83fcc 2019-08-22 martijn This value can be useful for logging.
447 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
448 6db83fcc 2019-08-22 martijn needs to be initialized with
449 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_MSGID .
450 6db83fcc 2019-08-22 martijn If not available the attribute is set to
452 6db83fcc 2019-08-22 martijn Filters in need of filter specific data can use
453 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_message
455 6db83fcc 2019-08-22 martijn .Va local_message .
456 58a6bc69 2022-12-05 martijn .It Vt char Va *username
457 58a6bc69 2022-12-05 martijn The username with which the session was successfully authenticated.
458 58a6bc69 2022-12-05 martijn .Nm osmtpd_need
459 58a6bc69 2022-12-05 martijn needs to be initialized with
460 58a6bc69 2022-12-05 martijn .DV OSMTPD_NEED_USERNAME .
461 58a6bc69 2022-12-05 martijn If not available or authentication failed is set to
462 58a6bc69 2022-12-05 martijn .Dv NULL .
463 6db83fcc 2019-08-22 martijn .It Vt char Va *mailfrom
464 2c1a20a1 2019-08-23 martijn The envelope MAIL FROM address in the SMTP transaction.
465 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
466 6db83fcc 2019-08-22 martijn needs to be initialized with
467 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_MAILFROM .
468 6db83fcc 2019-08-22 martijn If not available the attribute is set to
469 6db83fcc 2019-08-22 martijn .Dv NULL .
470 6db83fcc 2019-08-22 martijn .It Vt char Va **rcptto
471 2c1a20a1 2019-08-23 martijn The envelope RCPT TO address in the SMTP transaction.
472 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
473 6db83fcc 2019-08-22 martijn needs to be initialized with
474 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_RCPTTO .
475 6db83fcc 2019-08-22 martijn This attribute is a NULL-terminated array of address strings.
476 6db83fcc 2019-08-22 martijn If not available the first element in the array is set to
477 6db83fcc 2019-08-22 martijn .Dv NULL .
478 2c1a20a1 2019-08-23 martijn .It Vt uint64_t Va evpid
479 2c1a20a1 2019-08-23 martijn The envelope ID we're currently working on.
480 6db83fcc 2019-08-22 martijn .Nm osmtpd_need
481 6db83fcc 2019-08-22 martijn needs to be initialized with
482 6db83fcc 2019-08-22 martijn .Dv OSMTPD_NEED_EVPID .
483 6db83fcc 2019-08-22 martijn If not available the attribute is set to
485 2c1a20a1 2019-08-23 martijn .It Vt void Va *local_session
486 6db83fcc 2019-08-22 martijn Any filter specific data that needs to be stored during the session.
487 6db83fcc 2019-08-22 martijn This is initialized on
489 6db83fcc 2019-08-22 martijn creation by calling
490 6db83fcc 2019-08-22 martijn .Fa oncreate
491 6db83fcc 2019-08-22 martijn argument from
492 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_session .
493 2c1a20a1 2019-08-23 martijn .It Vt void Va *local_message
494 6db83fcc 2019-08-22 martijn Any filter specific data that needs to be stored during the message transaction.
495 6db83fcc 2019-08-22 martijn This is initialized on
497 6db83fcc 2019-08-22 martijn creation by calling
498 6db83fcc 2019-08-22 martijn .Fa oncreate
499 6db83fcc 2019-08-22 martijn argument from
500 6db83fcc 2019-08-22 martijn .Nm osmtpd_local_message .
504 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter
505 6db83fcc 2019-08-22 martijn class of functions must call one of
506 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_proceed ,
507 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_rewrite ,
508 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_reject
510 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_disconnect .
511 6db83fcc 2019-08-22 martijn This can be done either in the callback function itself, or at a later moment
512 6db83fcc 2019-08-22 martijn through another callback.
513 6db83fcc 2019-08-22 martijn Note that the session stalls until the
514 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter
515 6db83fcc 2019-08-22 martijn has been called.
517 6db83fcc 2019-08-22 martijn Exceptions to the above reply options are:
519 6db83fcc 2019-08-22 martijn .Bl -bullet -compact -width Ds
521 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_connect Ns 's
523 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter
524 6db83fcc 2019-08-22 martijn functions' callbacks without argument can't use
525 6db83fcc 2019-08-22 martijn .Nm osmtpd_filter_rewrite .
527 6db83fcc 2019-08-22 martijn .Nm osmtpd_register_filter_dataline Ns 's
528 6db83fcc 2019-08-22 martijn callback can only use osmtpd_filter_dataline.
531 8b9e9928 2025-01-30 kirill .Nm osmtpd_warn ,
532 8b9e9928 2025-01-30 kirill .Nm osmtpd_warnx ,
533 9aeab972 2019-08-22 martijn .Nm osmtpd_err
535 9aeab972 2019-08-22 martijn .Nm osmtpd_errx
536 9aeab972 2019-08-22 martijn can be used as a standin for
537 8b9e9928 2025-01-30 kirill .Xr warn 3
539 8b9e9928 2025-01-30 kirill .Xr warnx 3
541 9aeab972 2019-08-22 martijn .Xr err 3
543 9aeab972 2019-08-22 martijn .Xr errx 3
544 9aeab972 2019-08-22 martijn without printing the program name to stderr.
545 8b9e9928 2025-01-30 kirill Additionally,
546 8b9e9928 2025-01-30 kirill .Nm osmtpd_warn
548 8b9e9928 2025-01-30 kirill .Nm osmtpd_warnx
549 8b9e9928 2025-01-30 kirill prints the request ID on the logline when
552 8b9e9928 2025-01-30 kirill .Dv NULL .
553 6db83fcc 2019-08-22 martijn .Sh SEE ALSO
554 6db83fcc 2019-08-22 martijn .Xr event_init 3 ,
555 6db83fcc 2019-08-22 martijn .Xr smtpd.conf 5
556 6db83fcc 2019-08-22 martijn .Sh HISTORY
558 6db83fcc 2019-08-22 martijn .Nm osmtpd_run
559 6db83fcc 2019-08-22 martijn API first appeared in
560 6db83fcc 2019-08-22 martijn .Ox 6.6 .
561 6db83fcc 2019-08-22 martijn .Sh AUTHORS
562 6db83fcc 2019-08-22 martijn .An Martijn van Duren Aq Mt martijn@openbsd.org
