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