contrib/sendmail/include/libmilter/mfapi.h

   1 /*
   2  * Copyright (c) 1999-2004, 2006, 2008 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.80 2009/11/06 00:57:08 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 # if _FFR_MDS_NEGOTIATE
  22 #  define SMFI_VERSION  0x01000002      /* libmilter version number */
  23
  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 */
  30
  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)
  34
  35 # include <sys/types.h>
  36 # include <sys/socket.h>
  37
  38 #include "libmilter/mfdef.h"
  39
  40 # define LIBMILTER_API          extern
  41
  42
  43 /* Only need to export C interface if used by C++ source code */
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif /* __cplusplus */
  47
  48 #ifndef _SOCK_ADDR
  49 # define _SOCK_ADDR     struct sockaddr
  50 #endif /* ! _SOCK_ADDR */
  51
  52 /*
  53 **  libmilter functions return one of the following to indicate
  54 **  success/failure(/continue):
  55 */
  56
  57 #define MI_SUCCESS      0
  58 #define MI_FAILURE      (-1)
  59 #if _FFR_WORKERS_POOL
  60 # define MI_CONTINUE    1
  61 #endif /* _FFR_WORKERS_POOL */
  62
  63 /* "forward" declarations */
  64 typedef struct smfi_str SMFICTX;
  65 typedef struct smfi_str *SMFICTX_PTR;
  66
  67 typedef struct smfiDesc smfiDesc_str;
  68 typedef struct smfiDesc *smfiDesc_ptr;
  69
  70 /*
  71 **  Type which callbacks should return to indicate message status.
  72 **  This may take on one of the SMFIS_* values listed below.
  73 */
  74
  75 typedef int     sfsistat;
  76
  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 */
  82
  83 /* Some platforms don't define __P -- do it for them here: */
  84 #ifndef __P
  85 # ifdef __STDC__
  86 #  define __P(X) X
  87 # else /* __STDC__ */
  88 #  define __P(X) ()
  89 # endif /* __STDC__ */
  90 #endif /* __P */
  91
  92 #if SM_CONF_STDBOOL_H
  93 # include <stdbool.h>
  94 #else /* SM_CONF_STDBOOL_H */
  95 # ifndef __cplusplus
  96 #  ifndef bool
  97 #   ifndef __bool_true_false_are_defined
  98 typedef int     bool;
  99 #    define false       0
 100 #    define true        1
 101 #    define __bool_true_false_are_defined       1
 102 #   endif /* ! __bool_true_false_are_defined */
 103 #  endif /* bool */
 104 # endif /* ! __cplusplus */
 105 #endif /* SM_CONF_STDBOOL_H */
 106
 107 /*
 108 **  structure describing one milter
 109 */
 110
 111 struct smfiDesc
 112 {
 113         char            *xxfi_name;     /* filter name */
 114         int             xxfi_version;   /* version code -- do not change */
 115         unsigned long   xxfi_flags;     /* flags */
 116
 117         /* connection info filter */
 118         sfsistat        (*xxfi_connect) SM__P((SMFICTX *, char *, _SOCK_ADDR *));
 119
 120         /* SMTP HELO command filter */
 121         sfsistat        (*xxfi_helo) SM__P((SMFICTX *, char *));
 122
 123         /* envelope sender filter */
 124         sfsistat        (*xxfi_envfrom) SM__P((SMFICTX *, char **));
 125
 126         /* envelope recipient filter */
 127         sfsistat        (*xxfi_envrcpt) SM__P((SMFICTX *, char **));
 128
 129         /* header filter */
 130         sfsistat        (*xxfi_header) SM__P((SMFICTX *, char *, char *));
 131
 132         /* end of header */
 133         sfsistat        (*xxfi_eoh) SM__P((SMFICTX *));
 134
 135         /* body block */
 136         sfsistat        (*xxfi_body) SM__P((SMFICTX *, unsigned char *, size_t));
 137
 138         /* end of message */
 139         sfsistat        (*xxfi_eom) SM__P((SMFICTX *));
 140
 141         /* message aborted */
 142         sfsistat        (*xxfi_abort) SM__P((SMFICTX *));
 143
 144         /* connection cleanup */
 145         sfsistat        (*xxfi_close) SM__P((SMFICTX *));
 146
 147         /* any unrecognized or unimplemented command filter */
 148         sfsistat        (*xxfi_unknown) SM__P((SMFICTX *, const char *));
 149
 150         /* SMTP DATA command filter */
 151         sfsistat        (*xxfi_data) SM__P((SMFICTX *));
 152
 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 *));
 159
 160 #if 0
 161         /* signal handler callback, not yet implemented. */
 162         int             (*xxfi_signal) SM__P((int));
 163 #endif
 164
 165 };
 166
 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 *));
 177
 178 /*
 179 **  What the filter might do -- values to be ORed together for
 180 **  smfiDesc.xxfi_flags.
 181 */
 182
 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 */
 191
 192 /* filter may change "from" (envelope sender) */
 193 #define SMFIF_CHGFROM   0x00000040L
 194 #define SMFIF_ADDRCPT_PAR       0x00000080L     /* add recipients incl. args */
 195
 196 /* filter can send set of symbols (macros) that it wants */
 197 #define SMFIF_SETSYMLIST        0x00000100L
 198
 199
 200 /*
 201 **  Macro "places";
 202 **  Notes:
 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).
 207 */
 208
 209 #define SMFIM_FIRST     0       /* Do NOT use, internal marker only */
 210 #define SMFIM_CONNECT   0       /* connect */
 211 #define SMFIM_HELO      1       /* HELO/EHLO */
 212 #define SMFIM_ENVFROM   2       /* MAIL From */
 213 #define SMFIM_ENVRCPT   3       /* RCPT To */
 214 #define SMFIM_DATA      4       /* DATA */
 215 #define SMFIM_EOM       5       /* end of message (final dot) */
 216 #define SMFIM_EOH       6       /* end of header */
 217 #define SMFIM_LAST      6       /* Do NOT use, internal marker only */
 218
 219 /*
 220 **  Continue processing message/connection.
 221 */
 222
 223 #define SMFIS_CONTINUE  0
 224
 225 /*
 226 **  Reject the message/connection.
 227 **  No further routines will be called for this message
 228 **  (or connection, if returned from a connection-oriented routine).
 229 */
 230
 231 #define SMFIS_REJECT    1
 232
 233 /*
 234 **  Accept the message,
 235 **  but silently discard the message.
 236 **  No further routines will be called for this message.
 237 **  This is only meaningful from message-oriented routines.
 238 */
 239
 240 #define SMFIS_DISCARD   2
 241
 242 /*
 243 **  Accept the message/connection.
 244 **  No further routines will be called for this message
 245 **  (or connection, if returned from a connection-oriented routine;
 246 **  in this case, it causes all messages on this connection
 247 **  to be accepted without filtering).
 248 */
 249
 250 #define SMFIS_ACCEPT    3
 251
 252 /*
 253 **  Return a temporary failure, i.e.,
 254 **  the corresponding SMTP command will return a 4xx status code.
 255 **  In some cases this may prevent further routines from
 256 **  being called on this message or connection,
 257 **  although in other cases (e.g., when processing an envelope
 258 **  recipient) processing of the message will continue.
 259 */
 260
 261 #define SMFIS_TEMPFAIL  4
 262
 263 /*
 264 **  Do not send a reply to the MTA
 265 */
 266
 267 #define SMFIS_NOREPLY   7
 268
 269 /*
 270 **  Skip over rest of same callbacks, e.g., body.
 271 */
 272
 273 #define SMFIS_SKIP      8
 274
 275 /* xxfi_negotiate: use all existing protocol options/actions */
 276 #define SMFIS_ALL_OPTS  10
 277
 278 #if 0
 279 /*
 280 **  Filter Routine Details
 281 */
 282
 283 /* connection info filter */
 284 extern sfsistat xxfi_connect __P((SMFICTX *, char *, _SOCK_ADDR *));
 285
 286 /*
 287 **  xxfi_connect(ctx, hostname, hostaddr) Invoked on each connection
 288 **
 289 **      char *hostname; Host domain name, as determined by a reverse lookup
 290 **              on the host address.
 291 **      _SOCK_ADDR *hostaddr; Host address, as determined by a getpeername
 292 **              call on the SMTP socket.
 293 */
 294
 295 /* SMTP HELO command filter */
 296 extern sfsistat xxfi_helo __P((SMFICTX *, char *));
 297
 298 /*
 299 **  xxfi_helo(ctx, helohost) Invoked on SMTP HELO/EHLO command
 300 **
 301 **      char *helohost; Value passed to HELO/EHLO command, which should be
 302 **              the domain name of the sending host (but is, in practice,
 303 **              anything the sending host wants to send).
 304 */
 305
 306 /* envelope sender filter */
 307 extern sfsistat xxfi_envfrom __P((SMFICTX *, char **));
 308
 309 /*
 310 **  xxfi_envfrom(ctx, argv) Invoked on envelope from
 311 **
 312 **      char **argv; Null-terminated SMTP command arguments;
 313 **              argv[0] is guaranteed to be the sender address.
 314 **              Later arguments are the ESMTP arguments.
 315 */
 316
 317 /* envelope recipient filter */
 318 extern sfsistat xxfi_envrcpt __P((SMFICTX *, char **));
 319
 320 /*
 321 **  xxfi_envrcpt(ctx, argv) Invoked on each envelope recipient
 322 **
 323 **      char **argv; Null-terminated SMTP command arguments;
 324 **              argv[0] is guaranteed to be the recipient address.
 325 **              Later arguments are the ESMTP arguments.
 326 */
 327
 328 /* unknown command filter */
 329
 330 extern sfsistat *xxfi_unknown __P((SMFICTX *, const char *));
 331
 332 /*
 333 **  xxfi_unknown(ctx, arg) Invoked when SMTP command is not recognized or not
 334 **  implemented.
 335 **      const char *arg; Null-terminated SMTP command
 336 */
 337
 338 /* header filter */
 339 extern sfsistat xxfi_header __P((SMFICTX *, char *, char *));
 340
 341 /*
 342 **  xxfi_header(ctx, headerf, headerv) Invoked on each message header. The
 343 **  content of the header may have folded white space (that is, multiple
 344 **  lines with following white space) included.
 345 **
 346 **      char *headerf; Header field name
 347 **      char *headerv; Header field value
 348 */
 349
 350 /* end of header */
 351 extern sfsistat xxfi_eoh __P((SMFICTX *));
 352
 353 /*
 354 **  xxfi_eoh(ctx) Invoked at end of header
 355 */
 356
 357 /* body block */
 358 extern sfsistat xxfi_body __P((SMFICTX *, unsigned char *, size_t));
 359
 360 /*
 361 **  xxfi_body(ctx, bodyp, bodylen) Invoked for each body chunk. There may
 362 **  be multiple body chunks passed to the filter. End-of-lines are
 363 **  represented as received from SMTP (normally Carriage-Return/Line-Feed).
 364 **
 365 **      unsigned char *bodyp; Pointer to body data
 366 **      size_t bodylen; Length of body data
 367 */
 368
 369 /* end of message */
 370 extern sfsistat xxfi_eom __P((SMFICTX *));
 371
 372 /*
 373 **  xxfi_eom(ctx) Invoked at end of message. This routine can perform
 374 **  special operations such as modifying the message header, body, or
 375 **  envelope.
 376 */
 377
 378 /* message aborted */
 379 extern sfsistat xxfi_abort __P((SMFICTX *));
 380
 381 /*
 382 **  xxfi_abort(ctx) Invoked if message is aborted outside of the control of
 383 **  the filter, for example, if the SMTP sender issues an RSET command. If
 384 **  xxfi_abort is called, xxfi_eom will not be called and vice versa.
 385 */
 386
 387 /* connection cleanup */
 388 extern sfsistat xxfi_close __P((SMFICTX *));
 389
 390 /*
 391 **  xxfi_close(ctx) Invoked at end of the connection. This is called on
 392 **  close even if the previous mail transaction was aborted.
 393 */
 394 #endif /* 0 */
 395
 396 /*
 397 **  Additional information is passed in to the vendor filter routines using
 398 **  symbols. Symbols correspond closely to sendmail macros. The symbols
 399 **  defined depend on the context. The value of a symbol is accessed using:
 400 */
 401
 402 /* Return the value of a symbol. */
 403 LIBMILTER_API char * smfi_getsymval __P((SMFICTX *, char *));
 404
 405 /*
 406 **  Return the value of a symbol.
 407 **
 408 **      SMFICTX *ctx; Opaque context structure
 409 **      char *symname; The name of the symbol to access.
 410 */
 411
 412 /*
 413 **  Vendor filter routines that want to pass additional information back to
 414 **  the MTA for use in SMTP replies may call smfi_setreply before returning.
 415 */
 416
 417 LIBMILTER_API int smfi_setreply __P((SMFICTX *, char *, char *, char *));
 418
 419 /*
 420 **  Alternatively, smfi_setmlreply can be called if a multi-line SMTP reply
 421 **  is needed.
 422 */
 423
 424 LIBMILTER_API int smfi_setmlreply __P((SMFICTX *, const char *, const char *, ...));
 425
 426 /*
 427 **  Set the specific reply code to be used in response to the active
 428 **  command. If not specified, a generic reply code is used.
 429 **
 430 **      SMFICTX *ctx; Opaque context structure
 431 **      char *rcode; The three-digit (RFC 821) SMTP reply code to be
 432 **              returned, e.g., ``551''.
 433 **      char *xcode; The extended (RFC 2034) reply code, e.g., ``5.7.6''.
 434 **      char *message; The text part of the SMTP reply.
 435 */
 436
 437 /*
 438 **  The xxfi_eom routine is called at the end of a message (essentially,
 439 **  after the final DATA dot). This routine can call some special routines
 440 **  to modify the envelope, header, or body of the message before the
 441 **  message is enqueued. These routines must not be called from any vendor
 442 **  routine other than xxfi_eom.
 443 */
 444
 445 LIBMILTER_API int smfi_addheader __P((SMFICTX *, char *, char *));
 446
 447 /*
 448 **  Add a header to the message. It is not checked for standards
 449 **  compliance; the mail filter must ensure that no protocols are violated
 450 **  as a result of adding this header.
 451 **
 452 **      SMFICTX *ctx; Opaque context structure
 453 **      char *headerf; Header field name
 454 **      char *headerv; Header field value
 455 */
 456
 457 LIBMILTER_API int smfi_chgheader __P((SMFICTX *, char *, int, char *));
 458
 459 /*
 460 **  Change/delete a header in the message.  It is not checked for standards
 461 **  compliance; the mail filter must ensure that no protocols are violated
 462 **  as a result of adding this header.
 463 **
 464 **      SMFICTX *ctx; Opaque context structure
 465 **      char *headerf; Header field name
 466 **      int index; The Nth occurence of header field name
 467 **      char *headerv; New header field value (empty for delete header)
 468 */
 469
 470 LIBMILTER_API int smfi_insheader __P((SMFICTX *, int, char *, char *));
 471
 472 /*
 473 **  Insert a header into the message.  It is not checked for standards
 474 **  compliance; the mail filter must ensure that no protocols are violated
 475 **  as a result of adding this header.
 476 **
 477 **      SMFICTX *ctx; Opaque context structure
 478 **      int idx; index into the header list where the insertion should happen
 479 **      char *headerh; Header field name
 480 **      char *headerv; Header field value
 481 */
 482
 483 LIBMILTER_API int smfi_chgfrom __P((SMFICTX *, char *, char *));
 484
 485 /*
 486 **  Modify envelope sender address
 487 **
 488 **      SMFICTX *ctx; Opaque context structure
 489 **      char *mail; New envelope sender address
 490 **      char *args; ESMTP arguments
 491 */
 492
 493
 494 LIBMILTER_API int smfi_addrcpt __P((SMFICTX *, char *));
 495
 496 /*
 497 **  Add a recipient to the envelope
 498 **
 499 **      SMFICTX *ctx; Opaque context structure
 500 **      char *rcpt; Recipient to be added
 501 */
 502
 503 LIBMILTER_API int smfi_addrcpt_par __P((SMFICTX *, char *, char *));
 504
 505 /*
 506 **  Add a recipient to the envelope
 507 **
 508 **      SMFICTX *ctx; Opaque context structure
 509 **      char *rcpt; Recipient to be added
 510 **      char *args; ESMTP arguments
 511 */
 512
 513
 514 LIBMILTER_API int smfi_delrcpt __P((SMFICTX *, char *));
 515
 516 /*
 517 **  Send a "no-op" up to the MTA to tell it we're still alive, so long
 518 **  milter-side operations don't time out.
 519 **
 520 **      SMFICTX *ctx; Opaque context structure
 521 */
 522
 523 LIBMILTER_API int smfi_progress __P((SMFICTX *));
 524
 525 /*
 526 **  Delete a recipient from the envelope
 527 **
 528 **      SMFICTX *ctx; Opaque context structure
 529 **      char *rcpt; Envelope recipient to be deleted. This should be in
 530 **              exactly the form passed to xxfi_envrcpt or the address may
 531 **              not be deleted.
 532 */
 533
 534 LIBMILTER_API int smfi_replacebody __P((SMFICTX *, unsigned char *, int));
 535
 536 /*
 537 **  Replace the body of the message. This routine may be called multiple
 538 **  times if the body is longer than convenient to send in one call. End of
 539 **  line should be represented as Carriage-Return/Line Feed.
 540 **
 541 **      char *bodyp; Pointer to block of body information to insert
 542 **      int bodylen; Length of data pointed at by bodyp
 543 */
 544
 545 /*
 546 **  If the message is aborted (for example, if the SMTP sender sends the
 547 **  envelope but then does a QUIT or RSET before the data is sent),
 548 **  xxfi_abort is called. This can be used to reset state.
 549 */
 550
 551 /*
 552 **  Quarantine an envelope
 553 **
 554 **      SMFICTX *ctx; Opaque context structure
 555 **      char *reason: explanation
 556 */
 557
 558 LIBMILTER_API int smfi_quarantine __P((SMFICTX *ctx, char *reason));
 559
 560 /*
 561 **  Connection-private data (specific to an SMTP connection) can be
 562 **  allocated using the smfi_setpriv routine; routines can access private
 563 **  data using smfi_getpriv.
 564 */
 565
 566 LIBMILTER_API int smfi_setpriv __P((SMFICTX *, void *));
 567
 568 /*
 569 **  Set the private data pointer
 570 **
 571 **      SMFICTX *ctx; Opaque context structure
 572 **      void *privatedata; Pointer to private data area
 573 */
 574
 575 LIBMILTER_API void *smfi_getpriv __P((SMFICTX *));
 576
 577 /*
 578 **  Get the private data pointer
 579 **
 580 **      SMFICTX *ctx; Opaque context structure
 581 **      void *privatedata; Pointer to private data area
 582 */
 583
 584 LIBMILTER_API int smfi_setsymlist __P((SMFICTX *, int, char *));
 585
 586 /*
 587 **  Set list of symbols (macros) to receive
 588 **
 589 **      SMFICTX *ctx; Opaque context structure
 590 **      int where; where in the SMTP dialogue should the macros be sent
 591 **      char *macros; list of macros (space separated)
 592 */
 593
 594 #if _FFR_THREAD_MONITOR
 595 LIBMILTER_API int smfi_set_max_exec_time __P((unsigned int));
 596 #endif /* _FFR_THREAD_MONITOR */
 597
 598 #ifdef __cplusplus
 599 }
 600 #endif /* __cplusplus */
 601
 602 #endif /* ! _LIBMILTER_MFAPI_H */