epan/tap.h

   1 /** @file
   2  * packet tap interface   2002 Ronnie Sahlberg
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef __TAP_H__
  12 #define __TAP_H__
  13
  14 #include <epan/epan.h>
  15 #include <epan/packet_info.h>
  16 #include "ws_symbol_export.h"
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif /* __cplusplus */
  21
  22 /**
  23  * Status returned by the per-packet callback.
  24  */
  25 typedef enum {
  26         TAP_PACKET_DONT_REDRAW, /**< Packet processing succeeded, no need to redraw */
  27         TAP_PACKET_REDRAW,      /**< Packet processing succeeded, must redraw */
  28         TAP_PACKET_FAILED       /**< Packet processing failed, stop calling this tap */
  29 } tap_packet_status;
  30
  31 typedef unsigned tap_flags_t;
  32
  33 typedef void (*tap_reset_cb)(void *tapdata);
  34 typedef tap_packet_status (*tap_packet_cb)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data, tap_flags_t flags);
  35 typedef void (*tap_draw_cb)(void *tapdata);
  36 typedef void (*tap_finish_cb)(void *tapdata);
  37
  38 /**
  39  * Flags to indicate what a tap listener's packet routine requires.
  40  */
  41 #define TL_REQUIRES_NOTHING         0x00000000      /**< nothing */
  42 #define TL_REQUIRES_PROTO_TREE      0x00000001      /**< non-NULL protocol tree */
  43 #define TL_REQUIRES_COLUMNS         0x00000002      /**< columns */
  44 #define TL_REQUIRES_ERROR_PACKETS   0x00000004      /**< include packet even if pinfo->flags.in_error_pkt is set */
  45 #define TL_REQUIRES_PROTOCOLS       0x00000020      /**< don't fake protocols */
  46
  47 /** TL_REQUIRES_PROTO_TREE does not generate the full protocol tree;
  48  * any fields not referenced (e.g., in a filter) will still be "faked."
  49  * Note that if the tap does have a filter, it doesn't need
  50  * TL_REQUIRES_PROTO_TREE because filtering implies needing a tree.
  51  * It is for ensuring anything normally skipped with a NULL tree won't be,
  52  * which may include constructing data to pass to the tap. To make all
  53  * fields visible (which impacts performance), epan_set_always_visible()
  54  * can be used at the same time as registering the tap.
  55  * XXX - There should probably be a flag to set the tree visible.
  56  */
  57
  58 /** Flags to indicate what the tap listener does */
  59 #define TL_IS_DISSECTOR_HELPER      0x00000008      /**< tap helps a dissector do work
  60                                                                              ** but does not, itself, require dissection */
  61
  62 /** Flags to indicate what the packet cb should do */
  63 #define TL_IGNORE_DISPLAY_FILTER    0x00000010      /**< use packet, even if it would be filtered out */
  64 #define TL_DISPLAY_FILTER_IGNORED   0x00100000      /**< flag for the conversation handler */
  65
  66 /** Flags to indicate how the IP aggregation should behave during the statistics cb */
  67 #define TL_IP_AGGREGATION_NULL      0x00000100      /**< default analysis, no aggregation at all */
  68 #define TL_IP_AGGREGATION_ORI       0x00000200      /**< replace with subnets when possible, and keep original data */
  69 #define TL_IP_AGGREGATION_RESERVED  0x00000400      /**< reserved */
  70
  71 typedef struct {
  72         void (*register_tap_listener)(void);   /* routine to call to register tap listener */
  73 } tap_plugin;
  74
  75 /** Register tap plugin with the plugin system. */
  76 WS_DLL_PUBLIC void tap_register_plugin(const tap_plugin *plug);
  77
  78 /*
  79  * Entry in the table of built-in taps to register.
  80  */
  81 typedef struct _tap_reg {
  82     const char *cb_name;
  83     void (*cb_func)(void);
  84 } tap_reg_t;
  85
  86 /*
  87  * For all taps, call their register routines.
  88  * Must be called after plugins_init(), if plugins are supported,
  89  * and must be called only once in a program.
  90  *
  91  * XXX - should probably be handled by epan_init(), as the tap mechanism
  92  * is part of libwireshark.
  93  */
  94 WS_DLL_PUBLIC void register_all_tap_listeners(tap_reg_t const *tap_reg_listeners);
  95
  96 extern void tap_init(void);
  97
  98 /** This function registers that a dissector has the packet tap ability
  99  *  available.  The name parameter is the name of this tap and extensions can
 100  *  use open_tap(char *name,... to specify that it wants to receive packets/
 101  *  events from this tap.
 102  *
 103  *  This function is only to be called once, when the dissector initializes.
 104  *
 105  *  The return value from this call is later used as a parameter to the
 106  *  tap_packet(unsigned int *tap_id,...
 107  *  call so that the tap subsystem knows to which tap point this tapped
 108  *  packet is associated.
 109  */
 110 WS_DLL_PUBLIC int register_tap(const char *name);
 111
 112 /* Gets a GList of the tap names */
 113 WS_DLL_PUBLIC GList* get_tap_names(void);
 114
 115 /** This function will return the tap_id for the specific protocol tap
 116  *  or 0 if no such tap was found.
 117  */
 118 WS_DLL_PUBLIC int find_tap_id(const char *name);
 119
 120 /** Every time the dissector has finished dissecting a packet (and all
 121  *  subdissectors have returned) and if the dissector has been made "tappable"
 122  *  it will push some data to everyone tapping this layer by a call
 123  *  to tap_queue_packet().
 124  *  The first parameter is the tap_id returned by the register_tap()
 125  *  call for this dissector (so the tap system can keep track of who it came
 126  *  from and who is listening to it)
 127  *  The second is the packet_info structure which many tap readers will find
 128  *  interesting.
 129  *  The third argument is specific to each tap point or NULL if no additional
 130  *  data is available to this tap.  A tap point in say IP will probably want to
 131  *  push the IP header structure here. Same thing for TCP and ONCRPC.
 132  *
 133  *  The pinfo and the specific pointer are what is supplied to every listener
 134  *  in the read_callback() call made to every one currently listening to this
 135  *  tap.
 136  *
 137  *  The tap reader is responsible to know how to parse any structure pointed
 138  *  to by the tap specific data pointer.
 139  */
 140 WS_DLL_PUBLIC void tap_queue_packet(int tap_id, packet_info *pinfo, const void *tap_specific_data);
 141
 142 /** Functions used by file.c to drive the tap subsystem */
 143 WS_DLL_PUBLIC void tap_build_interesting(epan_dissect_t *edt);
 144
 145 /** This function is used to delete/initialize the tap queue and prime an
 146  *  epan_dissect_t with all the filters for tap listeners.
 147  *  To free the tap queue, we just prepend the used queue to the free queue.
 148  */
 149 extern void tap_queue_init(epan_dissect_t *edt);
 150
 151 /** this function is called after a packet has been fully dissected to push the tapped
 152  *  data to all extensions that has callbacks registered.
 153  */
 154
 155 extern void tap_push_tapped_queue(epan_dissect_t *edt);
 156
 157 /** This function is called after a packet has been fully dissected to push the tapped
 158  *  data to all extensions that has callbacks registered.
 159  */
 160
 161 WS_DLL_PUBLIC void reset_tap_listeners(void);
 162
 163 /** This function is called when we need to redraw all tap listeners, for example
 164  * when we open/start a new capture or if we need to rescan the packet list.
 165  * It should be called from a low priority thread say once every 3 seconds
 166  *
 167  * If draw_all is true, redraw all applications regardless if they have
 168  * changed or not.
 169  */
 170 WS_DLL_PUBLIC void draw_tap_listeners(bool draw_all);
 171
 172 /** this function attaches the tap_listener to the named tap.
 173  * function returns :
 174  *     NULL: ok.
 175  * non-NULL: error, return value points to GString containing error
 176  *           message.
 177  * @param tapname    The name of the tap we want to listen to.
 178  * @param tapdata    is the instance identifier. The tap system uses the value of this
 179  *                   pointer to distinguish between different instances of a tap.
 180  *                   Just make sure that it is unique by letting it be the pointer to a struct
 181  *                   holding all state variables. If you want to allow multiple concurrent
 182  *                   instances, just put ALL state variables inside a struct allocated by
 183  *                   g_malloc() and use that pointer.
 184  * @param fstring    is a pointer to a filter string.
 185  *                   If this is NULL, then the tap system will provide ALL packets passing the
 186  *                   tapped protocol to your listener.
 187  *                   If you specify a filter string here the tap system will first try
 188  *                   to apply this string to the packet and then only pass those packets that
 189  *                   matched the filter to your listener.
 190  *                   The syntax for the filter string is identical to normal display filters.
 191  *
 192  *                   NOTE: Specifying filter strings will have a significant performance impact
 193  *                   on your application and Wireshark. If possible it is MUCH better to take
 194  *                   unfiltered data and just filter it yourself in the packet-callback than
 195  *                   to specify a filter string.
 196  *                   ONLY use a filter string if no other option exist.
 197  *
 198  * @param flags      is a set of flags for the tap listener.  The flags that can be set are:
 199  *
 200  *                      TL_REQUIRES_PROTO_TREE
 201  *
 202  *                      set if your tap listener "packet" routine requires a protocol
 203  *                      tree to be built.  It will require a protocol tree to be
 204  *                      built if either
 205  *
 206  *                              1) it looks at the protocol tree in edt->tree
 207  *
 208  *                      or
 209  *
 210  *                              2) the tap-specific data passed to it is constructed only if
 211  *                                 the protocol tree is being built.
 212  *
 213  *                      TL_REQUIRES_COLUMNS
 214  *
 215  *                      set if your tap listener "packet" routine requires the column
 216  *                      strings to be constructed.
 217  *
 218  *                       If no flags are needed, use TL_REQUIRES_NOTHING.
 219  *
 220  * @param tap_reset  void (*reset)(void *tapdata)
 221  *                   This callback is called whenever Wireshark wants to inform your
 222  *                   listener that it is about to start [re]reading a capture file or a new capture
 223  *                   from an interface and that your application should reset any state it has
 224  *                   in the *tapdata instance.
 225  * @param tap_packet tap_packet_status (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data)
 226  *                   This callback is used whenever a new packet has arrived at the tap and that
 227  *                   it has passed the filter (if there were a filter).
 228  *                   The *data structure type is specific to each tap.
 229  *                   This function returns an bool and it should return
 230  *                    true, if the data in the packet caused state to be updated
 231  *                          (and thus a redraw of the window would later be required)
 232  *                    false, if we don't need to redraw the window.
 233  *                   NOTE: that (*packet) should be as fast and efficient as possible. Use this
 234  *                   function ONLY to store data for later and do the CPU-intensive processing
 235  *                   or GUI updates down in (*draw) instead.
 236  * @param tap_draw   void (*draw)(void *tapdata)
 237  *                   This callback is used when Wireshark wants your application to redraw its
 238  *                   output. It will usually not be called unless your application has received
 239  *                   new data through the (*packet) callback.
 240  *                   On some ports of Wireshark (gtk2) (*draw) will be called asynchronously
 241  *                   from a separate thread up to once every 2-3 seconds.
 242  *                   On other ports it might only be called once when the capture is finished
 243  *                   or the file has been [re]read completely.
 244  * @param tap_finish void (*finish)(void *tapdata)
 245  *                   This callback is called when your listener is removed.
 246  */
 247
 248 WS_DLL_PUBLIC GString *register_tap_listener(const char *tapname, void *tapdata,
 249     const char *fstring, unsigned flags, tap_reset_cb tap_reset,
 250     tap_packet_cb tap_packet, tap_draw_cb tap_draw,
 251     tap_finish_cb tap_finish) G_GNUC_WARN_UNUSED_RESULT;
 252
 253 /** This function sets a new dfilter to a tap listener */
 254 WS_DLL_PUBLIC GString *set_tap_dfilter(void *tapdata, const char *fstring);
 255
 256 /** This function recompiles dfilter for all registered tap listeners */
 257 WS_DLL_PUBLIC void tap_listeners_dfilter_recompile(void);
 258
 259 /** this function removes a tap listener */
 260 WS_DLL_PUBLIC void remove_tap_listener(void *tapdata);
 261
 262 /** This function sets new flags to a tap listener */
 263 WS_DLL_PUBLIC GString *set_tap_flags(void *tapdata, unsigned flags);
 264
 265 /**
 266  * Return true if we have one or more tap listeners that require dissection,
 267  * false otherwise.
 268  */
 269 WS_DLL_PUBLIC bool tap_listeners_require_dissection(void);
 270
 271 /**
 272  * Return true if we have one or more tap listeners that require the columns,
 273  * false otherwise.
 274  */
 275 WS_DLL_PUBLIC bool tap_listeners_require_columns(void);
 276
 277 /** Returns true there is an active tap listener for the specified tap id. */
 278 WS_DLL_PUBLIC bool have_tap_listener(int tap_id);
 279
 280 /** Return true if we have any tap listeners with filters, false otherwise. */
 281 WS_DLL_PUBLIC bool have_filtering_tap_listeners(void);
 282
 283 /** If any tap listeners have a filter with references to the currently
 284  * selected frame in the GUI (edt->tree), update them.
 285  */
 286 WS_DLL_PUBLIC void tap_listeners_load_field_references(epan_dissect_t *edt);
 287
 288 /**
 289  * Get the union of all the flags for all the tap listeners; that gives
 290  * an indication of whether the protocol tree, or the columns, are
 291  * required by any taps.
 292  */
 293 WS_DLL_PUBLIC unsigned union_of_tap_listener_flags(void);
 294
 295 /** This function can be used by a dissector to fetch any tapped data before
 296  * returning.
 297  * This can be useful if one wants to extract the data inside dissector  BEFORE
 298  * it exists as an alternative to the callbacks that are all called AFTER the
 299  * dissection has completed.
 300  *
 301  * Example: SMB2 uses this mechanism to extract the data tapped from NTLMSSP
 302  * containing the account and domain names before exiting.
 303  * Note that the SMB2 tap listener specifies all three callbacks as NULL.
 304  *
 305  * Beware: when using this mechanism to extract the tapped data you can not
 306  * use "filters" and should specify the "filter" as NULL when registering
 307  * the tap listener.
 308  */
 309 WS_DLL_PUBLIC const void *fetch_tapped_data(int tap_id, int idx);
 310
 311 /** Clean internal structures
 312  */
 313 extern void tap_cleanup(void);
 314
 315 #ifdef __cplusplus
 316 }
 317 #endif /* __cplusplus */
 318
 319 #endif /* __TAP_H__ */