2 * Copyright (c) 1999-2004, 2006, 2008, 2012 Proofpoint, Inc. and its suppliers.
5 * By using this file, you agree to the terms and conditions set
6 * forth in the LICENSE file which can be found at the top level of
7 * the sendmail distribution.
10 * $Id: mfapi.h,v 8.83 2013-11-22 20:51:27 ca Exp $
14 ** MFAPI.H -- Global definitions for mail filter library and mail filters.
17 #ifndef _LIBMILTER_MFAPI_H
18 # define _LIBMILTER_MFAPI_H 1
21 # if _FFR_MDS_NEGOTIATE
22 # define SMFI_VERSION 0x01000002 /* libmilter version number */
24 /* first libmilter version that has MDS support */
25 # define SMFI_VERSION_MDS 0x01000002
26 # else /* _FFR_MDS_NEGOTIATE */
27 # define SMFI_VERSION 0x01000001 /* libmilter version number */
28 # endif /* _FFR_MDS_NEGOTIATE */
29 #endif /* ! SMFI_VERSION */
31 #define SM_LM_VRS_MAJOR(v) (((v) & 0x7f000000) >> 24)
32 #define SM_LM_VRS_MINOR(v) (((v) & 0x007fff00) >> 8)
33 #define SM_LM_VRS_PLVL(v) ((v) & 0x0000007f)
35 # include <sys/types.h>
36 # include <sys/socket.h>
38 #include "libmilter/mfdef.h"
40 # define LIBMILTER_API extern
43 /* Only need to export C interface if used by C++ source code */
46 #endif /* __cplusplus */
49 # define _SOCK_ADDR struct sockaddr
50 #endif /* ! _SOCK_ADDR */
53 ** libmilter functions return one of the following to indicate
54 ** success/failure(/continue):
58 #define MI_FAILURE (-1)
60 # define MI_CONTINUE 1
61 #endif /* _FFR_WORKERS_POOL */
63 /* "forward" declarations */
64 typedef struct smfi_str SMFICTX;
65 typedef struct smfi_str *SMFICTX_PTR;
67 typedef struct smfiDesc smfiDesc_str;
68 typedef struct smfiDesc *smfiDesc_ptr;
71 ** Type which callbacks should return to indicate message status.
72 ** This may take on one of the SMFIS_* values listed below.
77 #if defined(__linux__) && defined(__GNUC__) && defined(__cplusplus) && __GNUC_MINOR__ >= 8
78 # define SM__P(X) __PMT(X)
79 #else /* __linux__ && __GNUC__ && __cplusplus && _GNUC_MINOR__ >= 8 */
80 # define SM__P(X) __P(X)
81 #endif /* __linux__ && __GNUC__ && __cplusplus && _GNUC_MINOR__ >= 8 */
83 /* Some platforms don't define __P -- do it for them here: */
89 # endif /* __STDC__ */
94 #else /* SM_CONF_STDBOOL_H */
97 # ifndef __bool_true_false_are_defined
101 # define __bool_true_false_are_defined 1
102 # endif /* ! __bool_true_false_are_defined */
104 # endif /* ! __cplusplus */
105 #endif /* SM_CONF_STDBOOL_H */
108 ** structure describing one milter
113 char *xxfi_name; /* filter name */
114 int xxfi_version; /* version code -- do not change */
115 unsigned long xxfi_flags; /* flags */
117 /* connection info filter */
118 sfsistat (*xxfi_connect) SM__P((SMFICTX *, char *, _SOCK_ADDR *));
120 /* SMTP HELO command filter */
121 sfsistat (*xxfi_helo) SM__P((SMFICTX *, char *));
123 /* envelope sender filter */
124 sfsistat (*xxfi_envfrom) SM__P((SMFICTX *, char **));
126 /* envelope recipient filter */
127 sfsistat (*xxfi_envrcpt) SM__P((SMFICTX *, char **));
130 sfsistat (*xxfi_header) SM__P((SMFICTX *, char *, char *));
133 sfsistat (*xxfi_eoh) SM__P((SMFICTX *));
136 sfsistat (*xxfi_body) SM__P((SMFICTX *, unsigned char *, size_t));
139 sfsistat (*xxfi_eom) SM__P((SMFICTX *));
141 /* message aborted */
142 sfsistat (*xxfi_abort) SM__P((SMFICTX *));
144 /* connection cleanup */
145 sfsistat (*xxfi_close) SM__P((SMFICTX *));
147 /* any unrecognized or unimplemented command filter */
148 sfsistat (*xxfi_unknown) SM__P((SMFICTX *, const char *));
150 /* SMTP DATA command filter */
151 sfsistat (*xxfi_data) SM__P((SMFICTX *));
153 /* negotiation callback */
154 sfsistat (*xxfi_negotiate) SM__P((SMFICTX *,
155 unsigned long, unsigned long,
156 unsigned long, unsigned long,
157 unsigned long *, unsigned long *,
158 unsigned long *, unsigned long *));
161 /* signal handler callback, not yet implemented. */
162 int (*xxfi_signal) SM__P((int));
167 LIBMILTER_API int smfi_opensocket __P((bool));
168 LIBMILTER_API int smfi_register __P((struct smfiDesc));
169 LIBMILTER_API int smfi_main __P((void));
170 LIBMILTER_API int smfi_setbacklog __P((int));
171 LIBMILTER_API int smfi_setdbg __P((int));
172 LIBMILTER_API int smfi_settimeout __P((int));
173 LIBMILTER_API int smfi_setconn __P((char *));
174 LIBMILTER_API int smfi_stop __P((void));
175 LIBMILTER_API size_t smfi_setmaxdatasize __P((size_t));
176 LIBMILTER_API int smfi_version __P((unsigned int *, unsigned int *, unsigned int *));
179 ** What the filter might do -- values to be ORed together for
180 ** smfiDesc.xxfi_flags.
183 #define SMFIF_NONE 0x00000000L /* no flags */
184 #define SMFIF_ADDHDRS 0x00000001L /* filter may add headers */
185 #define SMFIF_CHGBODY 0x00000002L /* filter may replace body */
186 #define SMFIF_MODBODY SMFIF_CHGBODY /* backwards compatible */
187 #define SMFIF_ADDRCPT 0x00000004L /* filter may add recipients */
188 #define SMFIF_DELRCPT 0x00000008L /* filter may delete recipients */
189 #define SMFIF_CHGHDRS 0x00000010L /* filter may change/delete headers */
190 #define SMFIF_QUARANTINE 0x00000020L /* filter may quarantine envelope */
192 /* filter may change "from" (envelope sender) */
193 #define SMFIF_CHGFROM 0x00000040L
194 #define SMFIF_ADDRCPT_PAR 0x00000080L /* add recipients incl. args */
196 /* filter can send set of symbols (macros) that it wants */
197 #define SMFIF_SETSYMLIST 0x00000100L
203 ** - must be coordinated with libmilter/engine.c and sendmail/milter.c
204 ** - the order MUST NOT be changed as it would break compatibility between
205 ** different versions. It's ok to append new entries however
206 ** (hence the list is not sorted by the SMT protocol steps).
209 #define SMFIM_NOMACROS (-1) /* Do NOT use, internal only */
210 #define SMFIM_FIRST 0 /* Do NOT use, internal marker only */
211 #define SMFIM_CONNECT 0 /* connect */
212 #define SMFIM_HELO 1 /* HELO/EHLO */
213 #define SMFIM_ENVFROM 2 /* MAIL From */
214 #define SMFIM_ENVRCPT 3 /* RCPT To */
215 #define SMFIM_DATA 4 /* DATA */
216 #define SMFIM_EOM 5 /* end of message (final dot) */
217 #define SMFIM_EOH 6 /* end of header */
218 #define SMFIM_LAST 6 /* Do NOT use, internal marker only */
221 ** Continue processing message/connection.
224 #define SMFIS_CONTINUE 0
227 ** Reject the message/connection.
228 ** No further routines will be called for this message
229 ** (or connection, if returned from a connection-oriented routine).
232 #define SMFIS_REJECT 1
235 ** Accept the message,
236 ** but silently discard the message.
237 ** No further routines will be called for this message.
238 ** This is only meaningful from message-oriented routines.
241 #define SMFIS_DISCARD 2
244 ** Accept the message/connection.
245 ** No further routines will be called for this message
246 ** (or connection, if returned from a connection-oriented routine;
247 ** in this case, it causes all messages on this connection
248 ** to be accepted without filtering).
251 #define SMFIS_ACCEPT 3
254 ** Return a temporary failure, i.e.,
255 ** the corresponding SMTP command will return a 4xx status code.
256 ** In some cases this may prevent further routines from
257 ** being called on this message or connection,
258 ** although in other cases (e.g., when processing an envelope
259 ** recipient) processing of the message will continue.
262 #define SMFIS_TEMPFAIL 4
265 ** Do not send a reply to the MTA
268 #define SMFIS_NOREPLY 7
271 ** Skip over rest of same callbacks, e.g., body.
276 /* xxfi_negotiate: use all existing protocol options/actions */
277 #define SMFIS_ALL_OPTS 10
281 ** Filter Routine Details
284 /* connection info filter */
285 extern sfsistat xxfi_connect __P((SMFICTX *, char *, _SOCK_ADDR *));
288 ** xxfi_connect(ctx, hostname, hostaddr) Invoked on each connection
290 ** char *hostname; Host domain name, as determined by a reverse lookup
291 ** on the host address.
292 ** _SOCK_ADDR *hostaddr; Host address, as determined by a getpeername
293 ** call on the SMTP socket.
296 /* SMTP HELO command filter */
297 extern sfsistat xxfi_helo __P((SMFICTX *, char *));
300 ** xxfi_helo(ctx, helohost) Invoked on SMTP HELO/EHLO command
302 ** char *helohost; Value passed to HELO/EHLO command, which should be
303 ** the domain name of the sending host (but is, in practice,
304 ** anything the sending host wants to send).
307 /* envelope sender filter */
308 extern sfsistat xxfi_envfrom __P((SMFICTX *, char **));
311 ** xxfi_envfrom(ctx, argv) Invoked on envelope from
313 ** char **argv; Null-terminated SMTP command arguments;
314 ** argv[0] is guaranteed to be the sender address.
315 ** Later arguments are the ESMTP arguments.
318 /* envelope recipient filter */
319 extern sfsistat xxfi_envrcpt __P((SMFICTX *, char **));
322 ** xxfi_envrcpt(ctx, argv) Invoked on each envelope recipient
324 ** char **argv; Null-terminated SMTP command arguments;
325 ** argv[0] is guaranteed to be the recipient address.
326 ** Later arguments are the ESMTP arguments.
329 /* unknown command filter */
331 extern sfsistat *xxfi_unknown __P((SMFICTX *, const char *));
334 ** xxfi_unknown(ctx, arg) Invoked when SMTP command is not recognized or not
336 ** const char *arg; Null-terminated SMTP command
340 extern sfsistat xxfi_header __P((SMFICTX *, char *, char *));
343 ** xxfi_header(ctx, headerf, headerv) Invoked on each message header. The
344 ** content of the header may have folded white space (that is, multiple
345 ** lines with following white space) included.
347 ** char *headerf; Header field name
348 ** char *headerv; Header field value
352 extern sfsistat xxfi_eoh __P((SMFICTX *));
355 ** xxfi_eoh(ctx) Invoked at end of header
359 extern sfsistat xxfi_body __P((SMFICTX *, unsigned char *, size_t));
362 ** xxfi_body(ctx, bodyp, bodylen) Invoked for each body chunk. There may
363 ** be multiple body chunks passed to the filter. End-of-lines are
364 ** represented as received from SMTP (normally Carriage-Return/Line-Feed).
366 ** unsigned char *bodyp; Pointer to body data
367 ** size_t bodylen; Length of body data
371 extern sfsistat xxfi_eom __P((SMFICTX *));
374 ** xxfi_eom(ctx) Invoked at end of message. This routine can perform
375 ** special operations such as modifying the message header, body, or
379 /* message aborted */
380 extern sfsistat xxfi_abort __P((SMFICTX *));
383 ** xxfi_abort(ctx) Invoked if message is aborted outside of the control of
384 ** the filter, for example, if the SMTP sender issues an RSET command. If
385 ** xxfi_abort is called, xxfi_eom will not be called and vice versa.
388 /* connection cleanup */
389 extern sfsistat xxfi_close __P((SMFICTX *));
392 ** xxfi_close(ctx) Invoked at end of the connection. This is called on
393 ** close even if the previous mail transaction was aborted.
398 ** Additional information is passed in to the vendor filter routines using
399 ** symbols. Symbols correspond closely to sendmail macros. The symbols
400 ** defined depend on the context. The value of a symbol is accessed using:
403 /* Return the value of a symbol. */
404 LIBMILTER_API char * smfi_getsymval __P((SMFICTX *, char *));
407 ** Return the value of a symbol.
409 ** SMFICTX *ctx; Opaque context structure
410 ** char *symname; The name of the symbol to access.
414 ** Vendor filter routines that want to pass additional information back to
415 ** the MTA for use in SMTP replies may call smfi_setreply before returning.
418 LIBMILTER_API int smfi_setreply __P((SMFICTX *, char *, char *, char *));
421 ** Alternatively, smfi_setmlreply can be called if a multi-line SMTP reply
425 LIBMILTER_API int smfi_setmlreply __P((SMFICTX *, const char *, const char *, ...));
428 ** Set the specific reply code to be used in response to the active
429 ** command. If not specified, a generic reply code is used.
431 ** SMFICTX *ctx; Opaque context structure
432 ** char *rcode; The three-digit (RFC 821) SMTP reply code to be
433 ** returned, e.g., ``551''.
434 ** char *xcode; The extended (RFC 2034) reply code, e.g., ``5.7.6''.
435 ** char *message; The text part of the SMTP reply.
439 ** The xxfi_eom routine is called at the end of a message (essentially,
440 ** after the final DATA dot). This routine can call some special routines
441 ** to modify the envelope, header, or body of the message before the
442 ** message is enqueued. These routines must not be called from any vendor
443 ** routine other than xxfi_eom.
446 LIBMILTER_API int smfi_addheader __P((SMFICTX *, char *, char *));
449 ** Add a header to the message. It is not checked for standards
450 ** compliance; the mail filter must ensure that no protocols are violated
451 ** as a result of adding this header.
453 ** SMFICTX *ctx; Opaque context structure
454 ** char *headerf; Header field name
455 ** char *headerv; Header field value
458 LIBMILTER_API int smfi_chgheader __P((SMFICTX *, char *, int, char *));
461 ** Change/delete a header in the message. It is not checked for standards
462 ** compliance; the mail filter must ensure that no protocols are violated
463 ** as a result of adding this header.
465 ** SMFICTX *ctx; Opaque context structure
466 ** char *headerf; Header field name
467 ** int index; The Nth occurence of header field name
468 ** char *headerv; New header field value (empty for delete header)
471 LIBMILTER_API int smfi_insheader __P((SMFICTX *, int, char *, char *));
474 ** Insert a header into the message. It is not checked for standards
475 ** compliance; the mail filter must ensure that no protocols are violated
476 ** as a result of adding this header.
478 ** SMFICTX *ctx; Opaque context structure
479 ** int idx; index into the header list where the insertion should happen
480 ** char *headerh; Header field name
481 ** char *headerv; Header field value
484 LIBMILTER_API int smfi_chgfrom __P((SMFICTX *, char *, char *));
487 ** Modify envelope sender address
489 ** SMFICTX *ctx; Opaque context structure
490 ** char *mail; New envelope sender address
491 ** char *args; ESMTP arguments
495 LIBMILTER_API int smfi_addrcpt __P((SMFICTX *, char *));
498 ** Add a recipient to the envelope
500 ** SMFICTX *ctx; Opaque context structure
501 ** char *rcpt; Recipient to be added
504 LIBMILTER_API int smfi_addrcpt_par __P((SMFICTX *, char *, char *));
507 ** Add a recipient to the envelope
509 ** SMFICTX *ctx; Opaque context structure
510 ** char *rcpt; Recipient to be added
511 ** char *args; ESMTP arguments
515 LIBMILTER_API int smfi_delrcpt __P((SMFICTX *, char *));
518 ** Send a "no-op" up to the MTA to tell it we're still alive, so long
519 ** milter-side operations don't time out.
521 ** SMFICTX *ctx; Opaque context structure
524 LIBMILTER_API int smfi_progress __P((SMFICTX *));
527 ** Delete a recipient from the envelope
529 ** SMFICTX *ctx; Opaque context structure
530 ** char *rcpt; Envelope recipient to be deleted. This should be in
531 ** exactly the form passed to xxfi_envrcpt or the address may
535 LIBMILTER_API int smfi_replacebody __P((SMFICTX *, unsigned char *, int));
538 ** Replace the body of the message. This routine may be called multiple
539 ** times if the body is longer than convenient to send in one call. End of
540 ** line should be represented as Carriage-Return/Line Feed.
542 ** char *bodyp; Pointer to block of body information to insert
543 ** int bodylen; Length of data pointed at by bodyp
547 ** If the message is aborted (for example, if the SMTP sender sends the
548 ** envelope but then does a QUIT or RSET before the data is sent),
549 ** xxfi_abort is called. This can be used to reset state.
553 ** Quarantine an envelope
555 ** SMFICTX *ctx; Opaque context structure
556 ** char *reason: explanation
559 LIBMILTER_API int smfi_quarantine __P((SMFICTX *ctx, char *reason));
562 ** Connection-private data (specific to an SMTP connection) can be
563 ** allocated using the smfi_setpriv routine; routines can access private
564 ** data using smfi_getpriv.
567 LIBMILTER_API int smfi_setpriv __P((SMFICTX *, void *));
570 ** Set the private data pointer
572 ** SMFICTX *ctx; Opaque context structure
573 ** void *privatedata; Pointer to private data area
576 LIBMILTER_API void *smfi_getpriv __P((SMFICTX *));
579 ** Get the private data pointer
581 ** SMFICTX *ctx; Opaque context structure
582 ** void *privatedata; Pointer to private data area
585 LIBMILTER_API int smfi_setsymlist __P((SMFICTX *, int, char *));
588 ** Set list of symbols (macros) to receive
590 ** SMFICTX *ctx; Opaque context structure
591 ** int where; where in the SMTP dialogue should the macros be sent
592 ** char *macros; list of macros (space separated)
595 #if _FFR_THREAD_MONITOR
596 LIBMILTER_API int smfi_set_max_exec_time __P((unsigned int));
597 #endif /* _FFR_THREAD_MONITOR */
601 #endif /* __cplusplus */
603 #endif /* ! _LIBMILTER_MFAPI_H */