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