src/src/local_scan.h

   1 /*************************************************
   2 *     Exim - an Internet mail transport agent    *
   3 *************************************************/
   4
   5 /* Copyright (c) University of Cambridge 1995 - 2020 */
   6 /* Copyright (c) The Exim Maintainers 2020 - 2021 */
   7 /* See the file NOTICE for conditions of use and distribution. */
   8
   9 /* This file is the header that is the only Exim header to be included in the
  10 source for the local_scan.c() function. It contains definitions that are made
  11 available for use in that function, and which are documented.  That source
  12 should first #define LOCAL_SCAN
  13
  14 Not every definition that becomes available to the compiler by the inclusion
  15 of this file is part of the local_scan API.  The "Adding a local scan function
  16 to Exim" chapter in the documentation is definitive.
  17
  18 This API is also used for functions called by the ${dlfunc expansion item.
  19 Source for those should first #define DLFUNC_IMPL and then include this file.
  20 Coders of dlfunc routines should read the notes on tainting at the start of
  21 store.c
  22 */
  23
  24
  25 /* Some basic types that make some things easier, the Exim configuration
  26 settings, and the store functions. */
  27
  28 #include <stdarg.h>
  29 #include <sys/types.h>
  30 #include "config.h"
  31 #include "mytypes.h"
  32 #include "store.h"
  33
  34
  35 /* Some people (Marc Merlin et al) are maintaining a patch that allows for
  36 dynamic local_scan() libraries. This code is not yet in Exim proper, but it
  37 helps the maintainers if we keep their ABI version numbers here. This may
  38 mutate into more general support later. The major number is increased when the
  39 ABI is changed in a non backward compatible way. The minor number is increased
  40 each time a new feature is added (in a way that doesn't break backward
  41 compatibility). */
  42
  43 #define LOCAL_SCAN_ABI_VERSION_MAJOR 5
  44 #define LOCAL_SCAN_ABI_VERSION_MINOR 1
  45 #define LOCAL_SCAN_ABI_VERSION \
  46   LOCAL_SCAN_ABI_VERSION_MAJOR.LOCAL_SCAN_ABI_VERSION_MINOR
  47
  48
  49
  50 /* The function and its return codes. */
  51
  52 extern int local_scan(int, uschar **);
  53
  54 enum {
  55   LOCAL_SCAN_ACCEPT,              /* Accept */
  56   LOCAL_SCAN_ACCEPT_FREEZE,       /* Accept, but freeze */
  57   LOCAL_SCAN_ACCEPT_QUEUE,        /* Accept, but no immediate delivery */
  58   LOCAL_SCAN_REJECT,              /* Permanent rejection */
  59   LOCAL_SCAN_REJECT_NOLOGHDR,     /* Permanent rejection, no log header */
  60   LOCAL_SCAN_TEMPREJECT,          /* Temporary rejection */
  61   LOCAL_SCAN_TEMPREJECT_NOLOGHDR  /* Temporary rejection, no log header */
  62 };
  63
  64
  65 /* Functions called by ${dlfunc{file}{func}{arg}...} return one of the five
  66 status codes defined immediately below. The function's first argument is either
  67 the result of expansion, or the error message in case of failure. The second
  68 and third arguments are standard argument count and vector, comprising the
  69 {arg} values specified in the expansion item. */
  70
  71 typedef int exim_dlfunc_t(uschar **yield, int argc, uschar *argv[]);
  72
  73
  74 /* Return codes from the support functions lss_match_xxx(). These are also the
  75 codes that dynamically-loaded ${dlfunc functions must return. */
  76
  77 #define  OK            0          /* Successful match */
  78 #define  DEFER         1          /* Defer - some problem */
  79 #define  FAIL          2          /* Matching failed */
  80 #define  ERROR         3          /* Internal or config error */
  81
  82 /* Extra return code for ${dlfunc functions */
  83
  84 #define  FAIL_FORCED   4          /* "Forced" failure */
  85
  86
  87 /* Available logging destinations */
  88
  89 #define LOG_MAIN        1    /* Write to the main log */
  90 #define LOG_PANIC       2    /* Write to the panic log */
  91 #define LOG_REJECT     16    /* Write to the reject log, with headers */
  92
  93
  94 /* Accessible debugging bits */
  95
  96 #define D_v                          0x00000001
  97 #define D_local_scan                 0x00000002
  98
  99
 100 /* Option types that can be used for local_scan_options. The boolean ones
 101 MUST be last so that they are contiguous with the internal boolean specials. */
 102
 103 enum { opt_stringptr, opt_int, opt_octint, opt_mkint, opt_Kint, opt_fixed,
 104   opt_time, opt_bool };
 105
 106
 107 /* The length of message identification strings. This is the id used internally
 108 by exim. The external version for use in Received: strings has a leading 'E'
 109 added to ensure it starts with a letter. */
 110
 111 #define MESSAGE_ID_LENGTH 16
 112
 113 /* The offset to the start of the data in the data file - this allows for
 114 the name of the data file to be present in the first line. */
 115
 116 #define SPOOL_DATA_START_OFFSET (MESSAGE_ID_LENGTH+3)
 117
 118 /* Structure definitions that are documented as visible in the function. */
 119
 120 typedef struct header_line {
 121   struct header_line *next;
 122   int    type;
 123   int    slen;
 124   uschar *text;
 125 } header_line;
 126
 127 /* Entries in lists options are in this form. */
 128
 129 typedef struct {
 130   const char *  name; /* should have been uschar but too late now */
 131   int           type;
 132   union {
 133     void *      value;
 134     long        offset;
 135     void (*     fn)();
 136   } v;
 137 } optionlist;
 138 #define OPT_OFF(s, field) {.offset = offsetof(s, field)}
 139
 140 /* Structure for holding information about an envelope address. The errors_to
 141 field is always NULL except for one_time aliases that had errors_to on the
 142 routers that generated them. */
 143
 144 typedef struct recipient_item {
 145   uschar *address;              /* the recipient address */
 146   int     pno;                  /* parent number for "one_time" alias, or -1 */
 147   uschar *errors_to;            /* the errors_to address or NULL */
 148   uschar *orcpt;                /* DSN orcpt */
 149   int     dsn_flags;            /* DSN flags */
 150 #ifdef EXPERIMENTAL_BRIGHTMAIL
 151   uschar *bmi_optin;
 152 #endif
 153 } recipient_item;
 154
 155
 156 /* Global variables that are documented as visible in the function. */
 157
 158 extern unsigned int debug_selector;    /* Debugging bits */
 159
 160 extern int     body_linecount;         /* Line count in body */
 161 extern int     body_zerocount;         /* Binary zero count in body */
 162 extern uschar *expand_string_message;  /* Error info for failing expansion */
 163 extern const uschar *headers_charset;  /* Charset for RFC 2047 decoding */
 164 extern header_line *header_last;       /* Final header */
 165 extern header_line *header_list;       /* First header */
 166 extern BOOL    host_checking;          /* Set when checking a host */
 167 extern uschar *interface_address;      /* Interface for incoming call */
 168 extern int     interface_port;         /* Port number for incoming call */
 169 extern uschar *message_id;             /* Internal id of message being handled */
 170 extern uschar *received_protocol;      /* Name of incoming protocol */
 171 extern int     recipients_count;       /* Number of recipients */
 172 extern recipient_item *recipients_list;/* List of recipient addresses */
 173 extern unsigned char *sender_address;  /* Sender address */
 174 extern uschar *sender_host_address;    /* IP address of sender, as chars */
 175 extern uschar *sender_host_authenticated; /* Name of authentication mechanism */
 176 extern uschar *sender_host_name;       /* Host name from lookup */
 177 extern int     sender_host_port;       /* Port number of sender */
 178 extern BOOL    smtp_batched_input;     /* TRUE if SMTP batch (no interaction) */
 179 extern BOOL    smtp_input;             /* TRUE if input is via SMTP */
 180
 181
 182 /* Functions that are documented as visible in local_scan(). */
 183
 184 extern int     child_close(pid_t, int);
 185 extern void    debug_printf(const char *, ...) PRINTF_FUNCTION(1,2);
 186 extern uschar *expand_string(uschar *);
 187 extern void    header_add(int, const char *, ...);
 188 extern void    header_add_at_position(BOOL, uschar *, BOOL, int, const char *, ...);
 189 extern void    header_remove(int, const uschar *);
 190 extern BOOL    header_testname(header_line *, const uschar *, int, BOOL);
 191 extern BOOL    header_testname_incomplete(header_line *, const uschar *, int, BOOL);
 192 extern void    log_write(unsigned int, int, const char *format, ...) PRINTF_FUNCTION(3,4);
 193 extern int     lss_b64decode(uschar *, uschar **);
 194 extern uschar *lss_b64encode(uschar *, int);
 195 extern int     lss_match_domain(uschar *, uschar *);
 196 extern int     lss_match_local_part(uschar *, uschar *, BOOL);
 197 extern int     lss_match_address(uschar *, uschar *, BOOL);
 198 extern int     lss_match_host(uschar *, uschar *, uschar *);
 199 extern void    receive_add_recipient(uschar *, int);
 200 extern BOOL    receive_remove_recipient(uschar *);
 201 extern uschar *rfc2047_decode(uschar *, BOOL, const uschar *, int, int *,
 202                               uschar **);
 203 extern int     smtp_fflush(void);
 204 extern void    smtp_printf(const char *, BOOL, ...) PRINTF_FUNCTION(1,3);
 205 extern void    smtp_vprintf(const char *, BOOL, va_list);
 206
 207 #define string_sprintf(fmt, ...) \
 208         string_sprintf_trc(fmt, US __FUNCTION__, __LINE__, __VA_ARGS__)
 209 extern uschar *string_sprintf_trc(const char *, const uschar *, unsigned, ...) ALMOST_PRINTF(1,4);
 210
 211 #define store_get(size, tainted) \
 212         store_get_3(size, tainted, __FUNCTION__, __LINE__)
 213 extern void   *store_get_3(int, BOOL, const char *, int)        ALLOC ALLOC_SIZE(1) WARN_UNUSED_RESULT;
 214 #define store_get_perm(size, tainted) \
 215         store_get_perm_3(size, tainted, __FUNCTION__, __LINE__)
 216 extern void   *store_get_perm_3(int, BOOL, const char *, int)   ALLOC ALLOC_SIZE(1) WARN_UNUSED_RESULT;
 217
 218
 219 #if defined(LOCAL_SCAN) || defined(DLFUNC_IMPL)
 220 /* When compiling a local_scan() file we want to rename a published API, so that
 221 we can use an inlined implementation in the compiles of the main Exim files,
 222 with the original name. */
 223
 224 # define string_copy(s) string_copy_function(s)
 225 # define string_copyn(s, n) string_copyn_function((s), (n))
 226 # define string_copy_taint(s, t) string_copy_taint_function((s), (t))
 227 # define child_open_exim(p)        child_open_exim_function((p), US"from local_scan")
 228 # define child_open_exim2(p, s, a) child_open_exim2_function((p), (s), (a), US"from local_scan")
 229 # define child_open(a,e,u,i,o,l) child_open_function((a),(e),(u),(i),(o),(l),US"from local_scan")
 230
 231 extern uschar * string_copy_function(const uschar *);
 232 extern uschar * string_copyn_function(const uschar *, int n);
 233 extern uschar * string_copy_taint_function(const uschar *, BOOL tainted);
 234 extern pid_t    child_open_exim_function(int *, const uschar *);
 235 extern pid_t    child_open_exim2_function(int *, uschar *, uschar *, const uschar *);
 236 extern pid_t    child_open_function(uschar **, uschar **, int, int *, int *, BOOL, const uschar *);
 237 #endif
 238
 239 /* End of local_scan.h */