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