src/src/local_scan.h

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