1 /* 2 * Copyright (c) 1999-2004 Sendmail, Inc. and its suppliers. 3 * All rights reserved. 4 * 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. 8 * 9 * 10 * $Id: mfapi.h,v 8.61 2006/05/04 17:02:01 ca Exp $ 11 */ 12 13 /* 14 ** MFAPI.H -- Global definitions for mail filter library and mail filters. 15 */ 16 17 #ifndef _LIBMILTER_MFAPI_H 18 # define _LIBMILTER_MFAPI_H 1 19 20 #ifndef SMFI_VERSION 21 # define SMFI_VERSION 2 /* version number */ 22 #endif /* ! SMFI_VERSION */ 23 24 # include <sys/types.h> 25 # include <sys/socket.h> 26 27 #include "libmilter/mfdef.h" 28 29 # define LIBMILTER_API extern 30 31 32 /* Only need to export C interface if used by C++ source code */ 33 #ifdef __cplusplus 34 extern "C" { 35 #endif /* __cplusplus */ 36 37 #ifndef _SOCK_ADDR 38 # define _SOCK_ADDR struct sockaddr 39 #endif /* ! _SOCK_ADDR */ 40 41 /* 42 ** libmilter functions return one of the following to indicate 43 ** success/failure: 44 */ 45 46 #define MI_SUCCESS 0 47 #define MI_FAILURE (-1) 48 49 /* "forward" declarations */ 50 typedef struct smfi_str SMFICTX; 51 typedef struct smfi_str *SMFICTX_PTR; 52 53 typedef struct smfiDesc smfiDesc_str; 54 typedef struct smfiDesc *smfiDesc_ptr; 55 56 /* 57 ** Type which callbacks should return to indicate message status. 58 ** This may take on one of the SMFIS_* values listed below. 59 */ 60 61 typedef int sfsistat; 62 63 #if defined(__linux__) && defined(__GNUC__) && defined(__cplusplus) && __GNUC_MINOR__ >= 8 64 # define SM__P(X) __PMT(X) 65 #else /* __linux__ && __GNUC__ && __cplusplus && _GNUC_MINOR__ >= 8 */ 66 # define SM__P(X) __P(X) 67 #endif /* __linux__ && __GNUC__ && __cplusplus && _GNUC_MINOR__ >= 8 */ 68 69 /* Some platforms don't define __P -- do it for them here: */ 70 #ifndef __P 71 # ifdef __STDC__ 72 # define __P(X) X 73 # else /* __STDC__ */ 74 # define __P(X) () 75 # endif /* __STDC__ */ 76 #endif /* __P */ 77 78 #if SM_CONF_STDBOOL_H 79 # include <stdbool.h> 80 #else /* SM_CONF_STDBOOL_H */ 81 # ifndef __cplusplus 82 # ifndef bool 83 # ifndef __bool_true_false_are_defined 84 typedef int bool; 85 # define __bool_true_false_are_defined 1 86 # endif /* ! __bool_true_false_are_defined */ 87 # endif /* bool */ 88 # endif /* ! __cplusplus */ 89 #endif /* SM_CONF_STDBOOL_H */ 90 91 /* 92 ** structure describing one milter 93 */ 94 95 struct smfiDesc 96 { 97 char *xxfi_name; /* filter name */ 98 int xxfi_version; /* version code -- do not change */ 99 unsigned long xxfi_flags; /* flags */ 100 101 /* connection info filter */ 102 sfsistat (*xxfi_connect) SM__P((SMFICTX *, char *, _SOCK_ADDR *)); 103 104 /* SMTP HELO command filter */ 105 sfsistat (*xxfi_helo) SM__P((SMFICTX *, char *)); 106 107 /* envelope sender filter */ 108 sfsistat (*xxfi_envfrom) SM__P((SMFICTX *, char **)); 109 110 /* envelope recipient filter */ 111 sfsistat (*xxfi_envrcpt) SM__P((SMFICTX *, char **)); 112 113 /* header filter */ 114 sfsistat (*xxfi_header) SM__P((SMFICTX *, char *, char *)); 115 116 /* end of header */ 117 sfsistat (*xxfi_eoh) SM__P((SMFICTX *)); 118 119 /* body block */ 120 sfsistat (*xxfi_body) SM__P((SMFICTX *, unsigned char *, size_t)); 121 122 /* end of message */ 123 sfsistat (*xxfi_eom) SM__P((SMFICTX *)); 124 125 /* message aborted */ 126 sfsistat (*xxfi_abort) SM__P((SMFICTX *)); 127 128 /* connection cleanup */ 129 sfsistat (*xxfi_close) SM__P((SMFICTX *)); 130 131 #if SMFI_VERSION > 2 132 /* any unrecognized or unimplemented command filter */ 133 sfsistat (*xxfi_unknown) SM__P((SMFICTX *, char *)); 134 #endif /* SMFI_VERSION > 2 */ 135 136 #if SMFI_VERSION > 3 137 /* SMTP DATA command filter */ 138 sfsistat (*xxfi_data) SM__P((SMFICTX *)); 139 #endif /* SMFI_VERSION > 3 */ 140 }; 141 142 LIBMILTER_API int smfi_opensocket __P((bool)); 143 LIBMILTER_API int smfi_register __P((struct smfiDesc)); 144 LIBMILTER_API int smfi_main __P((void)); 145 LIBMILTER_API int smfi_setbacklog __P((int)); 146 LIBMILTER_API int smfi_setdbg __P((int)); 147 LIBMILTER_API int smfi_settimeout __P((int)); 148 LIBMILTER_API int smfi_setconn __P((char *)); 149 LIBMILTER_API int smfi_stop __P((void)); 150 #if _FFR_MAXDATASIZE 151 LIBMILTER_API size_t smfi_setmaxdatasize __P((size_t)); 152 #endif /* _FFR_MAXDATASIZE */ 153 154 /* 155 ** What the filter might do -- values to be ORed together for 156 ** smfiDesc.xxfi_flags. 157 */ 158 159 #define SMFIF_NONE 0x00000000L /* no flags */ 160 #define SMFIF_ADDHDRS 0x00000001L /* filter may add headers */ 161 #define SMFIF_CHGBODY 0x00000002L /* filter may replace body */ 162 #define SMFIF_MODBODY SMFIF_CHGBODY /* backwards compatible */ 163 #define SMFIF_ADDRCPT 0x00000004L /* filter may add recipients */ 164 #define SMFIF_DELRCPT 0x00000008L /* filter may delete recipients */ 165 #define SMFIF_CHGHDRS 0x00000010L /* filter may change/delete headers */ 166 #define SMFIF_QUARANTINE 0x00000020L /* filter may quarantine envelope */ 167 168 /* 169 ** Continue processing message/connection. 170 */ 171 172 #define SMFIS_CONTINUE 0 173 174 /* 175 ** Reject the message/connection. 176 ** No further routines will be called for this message 177 ** (or connection, if returned from a connection-oriented routine). 178 */ 179 180 #define SMFIS_REJECT 1 181 182 /* 183 ** Accept the message, 184 ** but silently discard the message. 185 ** No further routines will be called for this message. 186 ** This is only meaningful from message-oriented routines. 187 */ 188 189 #define SMFIS_DISCARD 2 190 191 /* 192 ** Accept the message/connection. 193 ** No further routines will be called for this message 194 ** (or connection, if returned from a connection-oriented routine; 195 ** in this case, it causes all messages on this connection 196 ** to be accepted without filtering). 197 */ 198 199 #define SMFIS_ACCEPT 3 200 201 /* 202 ** Return a temporary failure, i.e., 203 ** the corresponding SMTP command will return a 4xx status code. 204 ** In some cases this may prevent further routines from 205 ** being called on this message or connection, 206 ** although in other cases (e.g., when processing an envelope 207 ** recipient) processing of the message will continue. 208 */ 209 210 #define SMFIS_TEMPFAIL 4 211 212 #if 0 213 /* 214 ** Filter Routine Details 215 */ 216 217 /* connection info filter */ 218 extern sfsistat xxfi_connect __P((SMFICTX *, char *, _SOCK_ADDR *)); 219 220 /* 221 ** xxfi_connect(ctx, hostname, hostaddr) Invoked on each connection 222 ** 223 ** char *hostname; Host domain name, as determined by a reverse lookup 224 ** on the host address. 225 ** _SOCK_ADDR *hostaddr; Host address, as determined by a getpeername 226 ** call on the SMTP socket. 227 */ 228 229 /* SMTP HELO command filter */ 230 extern sfsistat xxfi_helo __P((SMFICTX *, char *)); 231 232 /* 233 ** xxfi_helo(ctx, helohost) Invoked on SMTP HELO/EHLO command 234 ** 235 ** char *helohost; Value passed to HELO/EHLO command, which should be 236 ** the domain name of the sending host (but is, in practice, 237 ** anything the sending host wants to send). 238 */ 239 240 /* envelope sender filter */ 241 extern sfsistat xxfi_envfrom __P((SMFICTX *, char **)); 242 243 /* 244 ** xxfi_envfrom(ctx, argv) Invoked on envelope from 245 ** 246 ** char **argv; Null-terminated SMTP command arguments; 247 ** argv[0] is guaranteed to be the sender address. 248 ** Later arguments are the ESMTP arguments. 249 */ 250 251 /* envelope recipient filter */ 252 extern sfsistat xxfi_envrcpt __P((SMFICTX *, char **)); 253 254 /* 255 ** xxfi_envrcpt(ctx, argv) Invoked on each envelope recipient 256 ** 257 ** char **argv; Null-terminated SMTP command arguments; 258 ** argv[0] is guaranteed to be the recipient address. 259 ** Later arguments are the ESMTP arguments. 260 */ 261 262 /* unknown command filter */ 263 264 extern sfsistat *xxfi_unknown __P((SMFICTX *, char *)); 265 266 /* 267 ** xxfi_unknown(ctx, arg) Invoked when SMTP command is not recognized or not 268 ** implemented. 269 ** char *arg; Null-terminated SMTP command 270 */ 271 272 /* header filter */ 273 extern sfsistat xxfi_header __P((SMFICTX *, char *, char *)); 274 275 /* 276 ** xxfi_header(ctx, headerf, headerv) Invoked on each message header. The 277 ** content of the header may have folded white space (that is, multiple 278 ** lines with following white space) included. 279 ** 280 ** char *headerf; Header field name 281 ** char *headerv; Header field value 282 */ 283 284 /* end of header */ 285 extern sfsistat xxfi_eoh __P((SMFICTX *)); 286 287 /* 288 ** xxfi_eoh(ctx) Invoked at end of header 289 */ 290 291 /* body block */ 292 extern sfsistat xxfi_body __P((SMFICTX *, unsigned char *, size_t)); 293 294 /* 295 ** xxfi_body(ctx, bodyp, bodylen) Invoked for each body chunk. There may 296 ** be multiple body chunks passed to the filter. End-of-lines are 297 ** represented as received from SMTP (normally Carriage-Return/Line-Feed). 298 ** 299 ** unsigned char *bodyp; Pointer to body data 300 ** size_t bodylen; Length of body data 301 */ 302 303 /* end of message */ 304 extern sfsistat xxfi_eom __P((SMFICTX *)); 305 306 /* 307 ** xxfi_eom(ctx) Invoked at end of message. This routine can perform 308 ** special operations such as modifying the message header, body, or 309 ** envelope. 310 */ 311 312 /* message aborted */ 313 extern sfsistat xxfi_abort __P((SMFICTX *)); 314 315 /* 316 ** xxfi_abort(ctx) Invoked if message is aborted outside of the control of 317 ** the filter, for example, if the SMTP sender issues an RSET command. If 318 ** xxfi_abort is called, xxfi_eom will not be called and vice versa. 319 */ 320 321 /* connection cleanup */ 322 extern sfsistat xxfi_close __P((SMFICTX *)); 323 324 /* 325 ** xxfi_close(ctx) Invoked at end of the connection. This is called on 326 ** close even if the previous mail transaction was aborted. 327 */ 328 #endif /* 0 */ 329 330 /* 331 ** Additional information is passed in to the vendor filter routines using 332 ** symbols. Symbols correspond closely to sendmail macros. The symbols 333 ** defined depend on the context. The value of a symbol is accessed using: 334 */ 335 336 /* Return the value of a symbol. */ 337 LIBMILTER_API char * smfi_getsymval __P((SMFICTX *, char *)); 338 339 /* 340 ** Return the value of a symbol. 341 ** 342 ** SMFICTX *ctx; Opaque context structure 343 ** char *symname; The name of the symbol to access. 344 */ 345 346 /* 347 ** Vendor filter routines that want to pass additional information back to 348 ** the MTA for use in SMTP replies may call smfi_setreply before returning. 349 */ 350 351 LIBMILTER_API int smfi_setreply __P((SMFICTX *, char *, char *, char *)); 352 353 /* 354 ** Alternatively, smfi_setmlreply can be called if a multi-line SMTP reply 355 ** is needed. 356 */ 357 358 LIBMILTER_API int smfi_setmlreply __P((SMFICTX *, const char *, const char *, ...)); 359 360 /* 361 ** Set the specific reply code to be used in response to the active 362 ** command. If not specified, a generic reply code is used. 363 ** 364 ** SMFICTX *ctx; Opaque context structure 365 ** char *rcode; The three-digit (RFC 821) SMTP reply code to be 366 ** returned, e.g., ``551''. 367 ** char *xcode; The extended (RFC 2034) reply code, e.g., ``5.7.6''. 368 ** char *message; The text part of the SMTP reply. 369 */ 370 371 /* 372 ** The xxfi_eom routine is called at the end of a message (essentially, 373 ** after the final DATA dot). This routine can call some special routines 374 ** to modify the envelope, header, or body of the message before the 375 ** message is enqueued. These routines must not be called from any vendor 376 ** routine other than xxfi_eom. 377 */ 378 379 LIBMILTER_API int smfi_addheader __P((SMFICTX *, char *, char *)); 380 381 /* 382 ** Add a header to the message. It is not checked for standards 383 ** compliance; the mail filter must ensure that no protocols are violated 384 ** as a result of adding this header. 385 ** 386 ** SMFICTX *ctx; Opaque context structure 387 ** char *headerf; Header field name 388 ** char *headerv; Header field value 389 */ 390 391 LIBMILTER_API int smfi_chgheader __P((SMFICTX *, char *, int, char *)); 392 393 /* 394 ** Change/delete a header in the message. It is not checked for standards 395 ** compliance; the mail filter must ensure that no protocols are violated 396 ** as a result of adding this header. 397 ** 398 ** SMFICTX *ctx; Opaque context structure 399 ** char *headerf; Header field name 400 ** int index; The Nth occurence of header field name 401 ** char *headerv; New header field value (empty for delete header) 402 */ 403 404 LIBMILTER_API int smfi_insheader __P((SMFICTX *, int, char *, char *)); 405 406 /* 407 ** Insert a header into the message. It is not checked for standards 408 ** compliance; the mail filter must ensure that no protocols are violated 409 ** as a result of adding this header. 410 ** 411 ** SMFICTX *ctx; Opaque context structure 412 ** int idx; index into the header list where the insertion should happen 413 ** char *headerh; Header field name 414 ** char *headerv; Header field value 415 */ 416 417 LIBMILTER_API int smfi_addrcpt __P((SMFICTX *, char *)); 418 419 /* 420 ** Add a recipient to the envelope 421 ** 422 ** SMFICTX *ctx; Opaque context structure 423 ** char *rcpt; Recipient to be added 424 */ 425 426 LIBMILTER_API int smfi_delrcpt __P((SMFICTX *, char *)); 427 428 /* 429 ** Send a "no-op" up to the MTA to tell it we're still alive, so long 430 ** milter-side operations don't time out. 431 ** 432 ** SMFICTX *ctx; Opaque context structure 433 */ 434 435 LIBMILTER_API int smfi_progress __P((SMFICTX *)); 436 437 /* 438 ** Delete a recipient from the envelope 439 ** 440 ** SMFICTX *ctx; Opaque context structure 441 ** char *rcpt; Envelope recipient to be deleted. This should be in 442 ** exactly the form passed to xxfi_envrcpt or the address may 443 ** not be deleted. 444 */ 445 446 LIBMILTER_API int smfi_replacebody __P((SMFICTX *, unsigned char *, int)); 447 448 /* 449 ** Replace the body of the message. This routine may be called multiple 450 ** times if the body is longer than convenient to send in one call. End of 451 ** line should be represented as Carriage-Return/Line Feed. 452 ** 453 ** char *bodyp; Pointer to block of body information to insert 454 ** int bodylen; Length of data pointed at by bodyp 455 */ 456 457 /* 458 ** If the message is aborted (for example, if the SMTP sender sends the 459 ** envelope but then does a QUIT or RSET before the data is sent), 460 ** xxfi_abort is called. This can be used to reset state. 461 */ 462 463 /* 464 ** Quarantine an envelope 465 ** 466 ** SMFICTX *ctx; Opaque context structure 467 ** char *reason: explanation 468 */ 469 470 LIBMILTER_API int smfi_quarantine __P((SMFICTX *ctx, char *reason)); 471 472 /* 473 ** Connection-private data (specific to an SMTP connection) can be 474 ** allocated using the smfi_setpriv routine; routines can access private 475 ** data using smfi_getpriv. 476 */ 477 478 LIBMILTER_API int smfi_setpriv __P((SMFICTX *, void *)); 479 480 /* 481 ** Set the private data pointer 482 ** 483 ** SMFICTX *ctx; Opaque context structure 484 ** void *privatedata; Pointer to private data area 485 */ 486 487 LIBMILTER_API void *smfi_getpriv __P((SMFICTX *)); 488 489 #ifdef __cplusplus 490 } 491 #endif /* __cplusplus */ 492 493 #endif /* ! _LIBMILTER_MFAPI_H */ 494