epan/exported_pdu.h

   1 /*
   2  * exported_pdu.h
   3  * Routines for exported_pdu dissection
   4  * Copyright 2013, Anders Broman <anders-broman@ericsson.com>
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  23  */
  24
  25 #ifndef EXPORTED_PDU_H
  26 #define EXPORTED_PDU_H
  27
  28 #include <config.h>
  29
  30 #include "ws_symbol_export.h"
  31
  32 #include <glib.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif /* __cplusplus */
  37
  38 /*
  39  * Define different common tap names to extract PDUs at different layers,
  40  * otherwise one packet may be exported several times at different layers
  41  * if all taps are run.
  42  */
  43 #define EXPORT_PDU_TAP_NAME_LAYER_3 "OSI layer 3"
  44 #define EXPORT_PDU_TAP_NAME_LAYER_4 "OSI layer 4"
  45 #define EXPORT_PDU_TAP_NAME_LAYER_7 "OSI layer 7"
  46
  47 /* To add dynamically an export name, call the following function
  48    It returns the registered tap */
  49 WS_DLL_PUBLIC gint register_export_pdu_tap(const char *name);
  50 WS_DLL_PUBLIC GSList *get_export_pdu_tap_list(void);
  51
  52 /**
  53  * This struct is used as the data part of tap_queue_packet() and contains a
  54  * buffer with metadata of the protocol PDU included in the tvb in the struct.
  55  * the meta data is in TLV form, at least one tag MUST indicate what protocol is
  56  * in the PDU.
  57  * Buffer layout:
  58  *   0                   1                   2                   3
  59  *  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  60  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  61  * |      Option Code              |         Option Length         |
  62  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  63  * /                       Option Value                            /
  64  * /             variable length, aligned to 32 bits               /
  65  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  66  * /                                                               /
  67  * /                 . . . other options . . .                     /
  68  * /                                                               /
  69  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  70  * |   Option Code == opt_endofopt  |  Option Length == 0          |
  71  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  72  */
  73
  74 /*  Tag values
  75  *
  76  *  Do NOT add new values to this list without asking
  77  *  wireshark-dev[AT]wireshark.org for a value. Otherwise, you run the risk of
  78  *  using a value that's already being used for some other purpose, and of
  79  *  having tools that read exported_pdu captures not being able to handle
  80  *  captures with your new tag value, with no hope that they will ever be
  81  *  changed to do so (as that would destroy their ability to read captures
  82  *  using that value for that other purpose).
  83  */
  84 #define EXP_PDU_TAG_END_OF_OPT         0 /**< End-of-options Tag. */
  85 /* 1 - 9 reserved */
  86 #define EXP_PDU_TAG_OPTIONS_LENGTH    10 /**< Total length of the options excluding this TLV */
  87 #define EXP_PDU_TAG_LINKTYPE          11 /**< Deprecated - do not use */
  88 #define EXP_PDU_TAG_PROTO_NAME        12 /**< The value part should be an ASCII non NULL terminated string
  89                                           * of the registered dissector used by Wireshark e.g "sip"
  90                                           * Will be used to call the next dissector.
  91                                           */
  92 #define EXP_PDU_TAG_HEUR_PROTO_NAME   13 /**< The value part should be an ASCII non NULL terminated string
  93                                           * containing the heuristic unique short protocol name given
  94                                           * during registration, e.g "sip_udp"
  95                                           * Will be used to call the next dissector.
  96                                           */
  97 #define EXP_PDU_TAG_DISSECTOR_TABLE_NAME 14 /**< The value part should be an ASCII non NULL terminated string
  98                                           * containing the dissector table name given
  99                                           * during registration, e.g "gsm_map.v3.arg.opcode"
 100                                           * Will be used to call the next dissector.
 101                                           */
 102
 103 /* Add protocol type related tags here.
 104  * NOTE Only one protocol type tag may be present in a packet, the first one
 105  * found will be used*/
 106 /* 13 - 19 reserved */
 107 #define EXP_PDU_TAG_IPV4_SRC        20
 108 #define EXP_PDU_TAG_IPV4_DST        21
 109 #define EXP_PDU_TAG_IPV6_SRC        22
 110 #define EXP_PDU_TAG_IPV6_DST        23
 111
 112 #define EXP_PDU_TAG_PORT_TYPE       24  /**< value part is port_type enum from epan/address.h */
 113 #define EXP_PDU_TAG_SRC_PORT        25
 114 #define EXP_PDU_TAG_DST_PORT        26
 115
 116 #define EXP_PDU_TAG_SS7_OPC         28
 117 #define EXP_PDU_TAG_SS7_DPC         29
 118
 119 #define EXP_PDU_TAG_ORIG_FNO        30
 120
 121 #define EXP_PDU_TAG_DVBCI_EVT       31
 122
 123 #define EXP_PDU_TAG_DISSECTOR_TABLE_NAME_NUM_VAL 32 /**< value part is the numeric value to be used calling the dissector table
 124                                                       *  given with tag EXP_PDU_TAG_DISSECTOR_TABLE_NAME, must follow immediately after the table tag.
 125                                                       */
 126
 127 #define EXP_PDU_TAG_COL_PROT_TEXT   33 /**< Text string to put in COL_PROTOCOL, one use case is in conjunction with dissector tables where
 128                                         *   COL_PROTOCOL might not be filled in.
 129                                         */
 130
 131 /**< value part is structure passed into TCP subdissectors.  Format is:
 132     guint16 version          Export PDU version of structure (for backwards/forwards compatibility)
 133     guint32 seq              Sequence number of first byte in the data
 134     guint32 nxtseq           Sequence number of first byte after data
 135     guint32 lastackseq       Sequence number of last ack
 136     guint8 is_reassembled    This is reassembled data.
 137     guint16 flags            TCP flags
 138     guint16 urgent_pointer   Urgent pointer value for the current packet.
 139 */
 140 #define EXP_PDU_TAG_TCP_INFO_DATA  34
 141
 142 typedef struct _exp_pdu_data_t {
 143     guint        tlv_buffer_len;
 144     guint8      *tlv_buffer;
 145     guint        tvb_captured_length;
 146     guint        tvb_reported_length;
 147     tvbuff_t    *pdu_tvb;
 148 } exp_pdu_data_t;
 149
 150 #define EXP_PDU_TAG_IPV4_LEN            4
 151 #define EXP_PDU_TAG_IPV6_LEN            16
 152
 153 #define EXP_PDU_TAG_PORT_TYPE_LEN       4
 154 #define EXP_PDU_TAG_PORT_LEN            4
 155
 156 #define EXP_PDU_TAG_SS7_OPC_LEN         8 /* 4 bytes PC, 2 bytes standard type, 1 byte NI, 1 byte padding */
 157 #define EXP_PDU_TAG_SS7_DPC_LEN         8 /* 4 bytes PC, 2 bytes standard type, 1 byte NI, 1 byte padding */
 158
 159 #define EXP_PDU_TAG_ORIG_FNO_LEN        4
 160
 161 #define EXP_PDU_TAG_DVBCI_EVT_LEN       1
 162
 163 #define EXP_PDU_TAG_DISSECTOR_TABLE_NUM_VAL_LEN     4
 164
 165 /** Compute the size (in bytes) of a pdu item
 166 *
 167 @param pinfo Packet info that may contain data for the pdu item
 168 @param data optional data of the pdu item
 169 @return the size of the pdu item
 170 */
 171 typedef int (*exp_pdu_get_size)(packet_info *pinfo, void* data);
 172
 173 /** Populate a buffer with pdu item data
 174 *
 175 @param pinfo Packet info that may contain data for the PDU item
 176 @param data optional data of the PDU item
 177 @param tlv_buffer buffer to be populated with PDU item
 178 @param tlv_buffer_size size of buffer to be populated
 179 @return the number of bytes populated to the buffer (typically PDU item size)
 180 */
 181 typedef int (*exp_pdu_populate_data)(packet_info *pinfo, void* data, guint8 *tlv_buffer, guint32 tlv_buffer_size);
 182
 183 typedef struct exp_pdu_data_item
 184 {
 185     exp_pdu_get_size size_func;
 186     exp_pdu_populate_data populate_data;
 187     void* data;
 188 } exp_pdu_data_item_t;
 189
 190 /**
 191  Allocates and fills the exp_pdu_data_t struct according to the list of items
 192
 193  The tags in the tag buffer SHOULD be added in numerical order.
 194
 195  @param pinfo Packet info that may contain data for the PDU items
 196  @param proto_name Name of protocol that is exporting PDU
 197  @param tag_type Tag type for protocol's PDU. Must be EXP_PDU_TAG_PROTO_NAME or EXP_PDU_TAG_HEUR_PROTO_NAME.
 198  @param items PDU items to be exported
 199  @return filled exp_pdu_data_t struct
 200 */
 201 WS_DLL_PUBLIC exp_pdu_data_t *export_pdu_create_tags(packet_info *pinfo, const char* proto_name, guint16 tag_type, const exp_pdu_data_item_t **items);
 202
 203 /**
 204  Allocates and fills the exp_pdu_data_t struct with a common list of items
 205  The items that will be exported as the PDU are:
 206  1. Source IP
 207  2. Destintaiton IP
 208  3. Port type
 209  4. Source Port
 210  5. Destination Port
 211  6. Original frame number
 212
 213  @param pinfo Packet info that may contain data for the PDU items
 214  @param tag_type Tag type for protocol's PDU. Must be EXP_PDU_TAG_PROTO_NAME, EXP_PDU_TAG_HEUR_PROTO_NAME or EXP_PDU_TAG_DISSECTOR_TABLE_NAME
 215  @param proto_name Name of protocol that is exporting PDU
 216  @return filled exp_pdu_data_t struct
 217 */
 218 WS_DLL_PUBLIC exp_pdu_data_t *export_pdu_create_common_tags(packet_info *pinfo, const char *proto_name, guint16 tag_type);
 219
 220 WS_DLL_PUBLIC int exp_pdu_data_dissector_table_num_value_size(packet_info *pinfo, void* data);
 221 WS_DLL_PUBLIC int exp_pdu_data_dissector_table_num_value_populate_data(packet_info *pinfo, void* data, guint8 *tlv_buffer, guint32 buffer_size);
 222
 223 WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_src_ip;
 224 WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_dst_ip;
 225 WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_port_type;
 226 WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_src_port;
 227 WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_dst_port;
 228 WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_orig_frame_num;
 229
 230 extern void export_pdu_init(void);
 231
 232 extern void export_pdu_cleanup(void);
 233
 234 #ifdef __cplusplus
 235 }
 236 #endif /* __cplusplus */
 237
 238 #endif /* EXPORTED_PDU_H */