usr/src/cmd/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/26 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
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 #ifndef SMFI_VERSION
  25 #if _FFR_MDS_NEGOTIATE
  26 #define SMFI_VERSION    0x01000002      /* libmilter version number */
  27
  28 /* first libmilter version that has MDS support */
  29 #define SMFI_VERSION_MDS        0x01000002
  30 #else /* _FFR_MDS_NEGOTIATE */
  31 #define SMFI_VERSION    0x01000001      /* libmilter version number */
  32 #endif /* _FFR_MDS_NEGOTIATE */
  33 #endif /* ! SMFI_VERSION */
  34
  35 #define SM_LM_VRS_MAJOR(v)      (((v) & 0x7f000000) >> 24)
  36 #define SM_LM_VRS_MINOR(v)      (((v) & 0x007fff00) >> 8)
  37 #define SM_LM_VRS_PLVL(v)       ((v) & 0x0000007f)
  38
  39 #include <sys/types.h>
  40 #include <sys/socket.h>
  41
  42 #include <libmilter/mfdef.h>
  43
  44 #define LIBMILTER_API           extern
  45
  46 #ifndef _SOCK_ADDR
  47 #define _SOCK_ADDR      struct sockaddr
  48 #endif /* ! _SOCK_ADDR */
  49
  50 /*
  51  *  libmilter functions return one of the following to indicate
  52  *  success/failure(/continue):
  53  */
  54
  55 #define MI_SUCCESS      0
  56 #define MI_FAILURE      (-1)
  57 #if _FFR_WORKERS_POOL
  58 #define MI_CONTINUE     1
  59 #endif /* _FFR_WORKERS_POOL */
  60
  61 /* "forward" declarations */
  62 typedef struct smfi_str SMFICTX;
  63 typedef struct smfi_str *SMFICTX_PTR;
  64
  65 typedef struct smfiDesc smfiDesc_str;
  66 typedef struct smfiDesc *smfiDesc_ptr;
  67
  68 /*
  69  *  Type which callbacks should return to indicate message status.
  70  *  This may take on one of the SMFIS_* values listed below.
  71  */
  72
  73 typedef int     sfsistat;
  74
  75 #if defined(__linux__) && defined(__GNUC__) && defined(__cplusplus) && \
  76         __GNUC_MINOR__ >= 8
  77 #define SM__P(X)        __PMT(X)
  78 #else /* __linux__ && __GNUC__ && __cplusplus && _GNUC_MINOR__ >= 8 */
  79 #define SM__P(X)        __P(X)
  80 #endif /* __linux__ && __GNUC__ && __cplusplus && _GNUC_MINOR__ >= 8 */
  81
  82 /* Some platforms don't define __P -- do it for them here: */
  83 #ifndef __P
  84 #ifdef __STDC__
  85 #define __P(X) X
  86 #else /* __STDC__ */
  87 #define __P(X) ()
  88 #endif /* __STDC__ */
  89 #endif /* __P */
  90
  91 #if SM_CONF_STDBOOL_H
  92 #include <stdbool.h>
  93 #else /* SM_CONF_STDBOOL_H */
  94 #ifndef __cplusplus
  95 #ifndef bool
  96 #ifndef __bool_true_false_are_defined
  97 typedef int     bool;
  98 #define __bool_true_false_are_defined   1
  99 #endif /* ! __bool_true_false_are_defined */
 100 #endif /* bool */
 101 #endif /* ! __cplusplus */
 102 #endif /* SM_CONF_STDBOOL_H */
 103
 104 /*
 105  *  structure describing one milter
 106  */
 107
 108 struct smfiDesc
 109 {
 110         char            *xxfi_name;     /* filter name */
 111         int             xxfi_version;   /* version code -- do not change */
 112         unsigned long   xxfi_flags;     /* flags */
 113
 114         /* connection info filter */
 115         sfsistat        (*xxfi_connect) SM__P((SMFICTX *, char *,
 116                                                 _SOCK_ADDR *));
 117
 118         /* SMTP HELO command filter */
 119         sfsistat        (*xxfi_helo) SM__P((SMFICTX *, char *));
 120
 121         /* envelope sender filter */
 122         sfsistat        (*xxfi_envfrom) SM__P((SMFICTX *, char **));
 123
 124         /* envelope recipient filter */
 125         sfsistat        (*xxfi_envrcpt) SM__P((SMFICTX *, char **));
 126
 127         /* header filter */
 128         sfsistat        (*xxfi_header) SM__P((SMFICTX *, char *, char *));
 129
 130         /* end of header */
 131         sfsistat        (*xxfi_eoh) SM__P((SMFICTX *));
 132
 133         /* body block */
 134         sfsistat        (*xxfi_body) SM__P((SMFICTX *, unsigned char *,
 135                                                 size_t));
 136
 137         /* end of message */
 138         sfsistat        (*xxfi_eom) SM__P((SMFICTX *));
 139
 140         /* message aborted */
 141         sfsistat        (*xxfi_abort) SM__P((SMFICTX *));
 142
 143         /* connection cleanup */
 144         sfsistat        (*xxfi_close) SM__P((SMFICTX *));
 145
 146         /* any unrecognized or unimplemented command filter */
 147         sfsistat        (*xxfi_unknown) SM__P((SMFICTX *, const char *));
 148
 149         /* SMTP DATA command filter */
 150         sfsistat        (*xxfi_data) SM__P((SMFICTX *));
 151
 152         /* negotiation callback */
 153         sfsistat        (*xxfi_negotiate) SM__P((SMFICTX *,
 154                                         unsigned long, unsigned long,
 155                                         unsigned long, unsigned long,
 156                                         unsigned long *, unsigned long *,
 157                                         unsigned long *, unsigned long *));
 158
 159 #if 0
 160         /* signal handler callback, not yet implemented. */
 161         int             (*xxfi_signal) SM__P((int));
 162 #endif
 163
 164 };
 165
 166 LIBMILTER_API int smfi_opensocket __P((bool));
 167 LIBMILTER_API int smfi_register __P((struct smfiDesc));
 168 LIBMILTER_API int smfi_main __P((void));
 169 LIBMILTER_API int smfi_setbacklog __P((int));
 170 LIBMILTER_API int smfi_setdbg __P((int));
 171 LIBMILTER_API int smfi_settimeout __P((int));
 172 LIBMILTER_API int smfi_setconn __P((char *));
 173 LIBMILTER_API int smfi_stop __P((void));
 174 LIBMILTER_API size_t smfi_setmaxdatasize __P((size_t));
 175 LIBMILTER_API int smfi_version __P((unsigned int *, unsigned int *,
 176     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 /*
 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.
 430  *
 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.
 436  */
 437
 438 /*
 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.
 444  */
 445
 446 LIBMILTER_API int smfi_addheader __P((SMFICTX *, char *, char *));
 447
 448 /*
 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.
 452  *
 453  *      SMFICTX *ctx; Opaque context structure
 454  *      char *headerf; Header field name
 455  *      char *headerv; Header field value
 456  */
 457
 458 LIBMILTER_API int smfi_chgheader __P((SMFICTX *, char *, int, char *));
 459
 460 /*
 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.
 464  *
 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)
 469  */
 470
 471 LIBMILTER_API int smfi_insheader __P((SMFICTX *, int, char *, char *));
 472
 473 /*
 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.
 477  *
 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
 482  */
 483
 484 LIBMILTER_API int smfi_chgfrom __P((SMFICTX *, char *, char *));
 485
 486 /*
 487  *  Modify envelope sender address
 488  *
 489  *     SMFICTX *ctx; Opaque context structure
 490  *     char *mail; New envelope sender address
 491  *     char *args; ESMTP arguments
 492  */
 493
 494
 495 LIBMILTER_API int smfi_addrcpt __P((SMFICTX *, char *));
 496
 497 /*
 498  *  Add a recipient to the envelope
 499  *
 500  *      SMFICTX *ctx; Opaque context structure
 501  *      char *rcpt; Recipient to be added
 502  */
 503
 504 LIBMILTER_API int smfi_addrcpt_par __P((SMFICTX *, char *, char *));
 505
 506 /*
 507  *  Add a recipient to the envelope
 508  *
 509  *      SMFICTX *ctx; Opaque context structure
 510  *      char *rcpt; Recipient to be added
 511  *      char *args; ESMTP arguments
 512  */
 513
 514
 515 LIBMILTER_API int smfi_delrcpt __P((SMFICTX *, char *));
 516
 517 /*
 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.
 520  *
 521  *      SMFICTX *ctx; Opaque context structure
 522  */
 523
 524 LIBMILTER_API int smfi_progress __P((SMFICTX *));
 525
 526 /*
 527  *  Delete a recipient from the envelope
 528  *
 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
 532  *              not be deleted.
 533  */
 534
 535 LIBMILTER_API int smfi_replacebody __P((SMFICTX *, unsigned char *, int));
 536
 537 /*
 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.
 541  *
 542  *      char *bodyp; Pointer to block of body information to insert
 543  *      int bodylen; Length of data pointed at by bodyp
 544  */
 545
 546 /*
 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.
 550  */
 551
 552 /*
 553  *  Quarantine an envelope
 554  *
 555  *      SMFICTX *ctx; Opaque context structure
 556  *      char *reason: explanation
 557  */
 558
 559 LIBMILTER_API int smfi_quarantine __P((SMFICTX *ctx, char *reason));
 560
 561 /*
 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.
 565  */
 566
 567 LIBMILTER_API int smfi_setpriv __P((SMFICTX *, void *));
 568
 569 /*
 570  *  Set the private data pointer
 571  *
 572  *      SMFICTX *ctx; Opaque context structure
 573  *      void *privatedata; Pointer to private data area
 574  */
 575
 576 LIBMILTER_API void *smfi_getpriv __P((SMFICTX *));
 577
 578 /*
 579  *  Get the private data pointer
 580  *
 581  *      SMFICTX *ctx; Opaque context structure
 582  *      void *privatedata; Pointer to private data area
 583  */
 584
 585 LIBMILTER_API int smfi_setsymlist __P((SMFICTX *, int, char *));
 586
 587 /*
 588  *  Set list of symbols (macros) to receive
 589  *
 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)
 593  */
 594
 595 #if _FFR_THREAD_MONITOR
 596 LIBMILTER_API int smfi_set_max_exec_time __P((unsigned int));
 597 #endif /* _FFR_THREAD_MONITOR */
 598
 599 #ifdef __cplusplus
 600 }
 601 #endif
 602
 603 #endif /* !_LIBMILTER_MFAPI_H */