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