doc/packet-PROTOABBREV.c

   1 /* packet-PROTOABBREV.c
   2  * Routines for PROTONAME dissection
   3  * Copyright YEARS, YOUR_NAME <YOUR_EMAIL_ADDRESS>
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: LICENSE
  10  */
  11
  12 /*
  13  * (A short description of the protocol including links to specifications,
  14  *  detailed documentation, etc.)
  15  */
  16
  17 #include "config.h"
  18 /* Define the name for the logging domain (try to avoid collisions with existing domains) */
  19 #define WS_LOG_DOMAIN "PROTOABBREV"
  20
  21 /* Global header providing a minimum base set of required macros and APIs */
  22 #include <wireshark.h>
  23
  24 #if 0
  25 /* "System" includes used only as needed */
  26 #include <stdio.h>
  27 #include <stdlib.h>
  28 #include <string.h>
  29 ...
  30 #endif
  31
  32 #include <epan/packet.h>   /* Required dissection API header */
  33 #include <epan/expert.h>   /* Include only as needed */
  34 #include <epan/prefs.h>    /* Include only as needed */
  35
  36 #if 0
  37 /* IF AND ONLY IF your protocol dissector exposes code to other dissectors
  38  * (which most dissectors don't need to do) then the 'public' prototypes and
  39  * data structures can go in the header file packet-PROTOABBREV.h. If not, then
  40  * a header file is not needed at all and this #include statement can be
  41  * removed. */
  42 #include "packet-PROTOABBREV.h"
  43 #endif
  44
  45 /* Some protocols may need code from other dissectors, as here for
  46  * ssl_dissector_add()
  47  */
  48 #include "packet-tls.h"
  49
  50 /* Prototypes */
  51 /* (Required to prevent [-Wmissing-prototypes] warnings */
  52 void proto_reg_handoff_PROTOABBREV(void);
  53 void proto_register_PROTOABBREV(void);
  54
  55 /* Initialize the protocol and registered fields */
  56 static int proto_PROTOABBREV;
  57 static int hf_FIELDABBREV;
  58 static expert_field ei_PROTOABBREV_EXPERTABBREV;
  59
  60 static dissector_handle_t PROTOABBREV_handle;
  61 static dissector_handle_t PROTOABBREV_tls_handle;
  62
  63 /* Global sample preference ("controls" display of numbers) */
  64 static bool pref_hex;
  65 /* Global sample port preference - real port preferences should generally
  66  * default to "" (for a range) or 0 (for a single uint) unless there is an
  67  * IANA-registered (or equivalent) port for your protocol. */
  68 #define PROTOABBREV_TLS_PORT 5678
  69 static unsigned tls_port_pref = PROTOABBREV_TLS_PORT;
  70
  71 #define PROTOABBREV_TCP_PORTS "1234"
  72 static range_t *tcp_port_range = PROTOABBREV_TCP_PORTS;
  73
  74 /* Initialize the subtree pointers */
  75 static int ett_PROTOABBREV;
  76
  77 /* A sample #define of the minimum length (in bytes) of the protocol data.
  78  * If data is received with fewer than this many bytes it is rejected by
  79  * the current dissector. */
  80 #define PROTOABBREV_MIN_LENGTH 8
  81
  82 /* Code to actually dissect the packets */
  83 static int
  84 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree,
  85         void *data _U_)
  86 {
  87     /* Set up structures needed to add the protocol subtree and manage it */
  88     proto_item *ti, *expert_ti;
  89     proto_tree *PROTOABBREV_tree;
  90     /* Other misc. local variables. */
  91     unsigned offset = 0;
  92     int      len    = 0;
  93
  94     /*** HEURISTICS ***/
  95
  96     /* First, if at all possible, do some heuristics to check if the packet
  97      * cannot possibly belong to your protocol.  This is especially important
  98      * for protocols directly on top of TCP or UDP where port collisions are
  99      * common place (e.g., even though your protocol uses a well known port,
 100      * someone else may set up, for example, a web server on that port which,
 101      * if someone analyzed that web server's traffic in Wireshark, would result
 102      * in Wireshark handing an HTTP packet to your dissector).
 103      *
 104      * For example:
 105      */
 106
 107     /* Check that the packet is long enough for it to belong to us. */
 108     if (tvb_reported_length(tvb) < PROTOABBREV_MIN_LENGTH)
 109         return 0;
 110
 111     /* Check that there's enough data present to run the heuristics. If there
 112      * isn't, reject the packet; it will probably be dissected as data and if
 113      * the user wants it dissected despite it being short they can use the
 114      * "Decode-As" functionality. If your heuristic needs to look very deep into
 115      * the packet you may not want to require *all* data to be present, but you
 116      * should ensure that the heuristic does not access beyond the captured
 117      * length of the packet regardless. */
 118     if (tvb_captured_length(tvb) < MAX_NEEDED_FOR_HEURISTICS)
 119         return 0;
 120
 121     /* Fetch some values from the packet header using tvb_get_*(). If these
 122      * values are not valid/possible in your protocol then return 0 to give
 123      * some other dissector a chance to dissect it. */
 124     if ( TEST_HEURISTICS_FAIL )
 125         return 0;
 126
 127     /*** COLUMN DATA ***/
 128
 129     /* There are two normal columns to fill in: the 'Protocol' column which
 130      * is narrow and generally just contains the constant string 'PROTOABBREV',
 131      * and the 'Info' column which can be much wider and contain misc. summary
 132      * information (for example, the port number for TCP packets).
 133      *
 134      * If you are setting the column to a constant string, use "col_set_str()",
 135      * as it's more efficient than the other "col_set_XXX()" calls.
 136      *
 137      * If
 138      * - you may be appending to the column later OR
 139      * - you have constructed the string locally OR
 140      * - the string was returned from a call to val_to_str()
 141      * then use "col_add_str()" instead, as that takes a copy of the string.
 142      *
 143      * The function "col_add_fstr()" can be used instead of "col_add_str()"; it
 144      * takes "printf()"-like arguments. Don't use "col_add_fstr()" with a format
 145      * string of "%s" - just use "col_add_str()" or "col_set_str()", as it's
 146      * more efficient than "col_add_fstr()".
 147      *
 148      * For full details see section 1.4 of README.dissector.
 149      */
 150
 151     /* Set the Protocol column to the constant string of PROTOABBREV */
 152     col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
 153
 154 #if 0
 155     /* If you will be fetching any data from the packet before filling in
 156      * the Info column, clear that column first in case the calls to fetch
 157      * data from the packet throw an exception so that the Info column doesn't
 158      * contain data left over from the previous dissector: */
 159     col_clear(pinfo->cinfo, COL_INFO);
 160 #endif
 161
 162     /* Some protocols need to be parsed differently for packets sent to the
 163      * registered (server) port versus packets sent from the server port
 164      * to an ephemeral client port.
 165      */
 166     if (value_is_in_range(tcp_port_range, pinfo->destport)) {
 167         col_set_str(pinfo->cinfo, COL_INFO, "XXX Request");
 168     } else {
 169         col_set_str(pinfo->cinfo, COL_INFO, "XXX Reply");
 170     }
 171
 172     /*** PROTOCOL TREE ***/
 173
 174     /* Now we will create a sub-tree for our protocol and start adding fields
 175      * to display under that sub-tree. Most of the time the only functions you
 176      * will need are proto_tree_add_item() and proto_item_add_subtree().
 177      *
 178      * NOTE: The offset and length values in the call to proto_tree_add_item()
 179      * define what data bytes to highlight in the hex display window when the
 180      * line in the protocol tree display corresponding to that item is selected.
 181      *
 182      * Supplying a length of -1 tells Wireshark to highlight all data from the
 183      * offset to the end of the packet.
 184      */
 185
 186     /* create display subtree for the protocol */
 187     ti = proto_tree_add_item(tree, proto_PROTOABBREV, tvb, 0, -1, ENC_NA);
 188
 189     PROTOABBREV_tree = proto_item_add_subtree(ti, ett_PROTOABBREV);
 190
 191     /* Add an item to the subtree, see section 1.5 of README.dissector for more
 192      * information. */
 193     expert_ti = proto_tree_add_item(PROTOABBREV_tree, hf_FIELDABBREV, tvb,
 194             offset, len, ENC_xxx);
 195     offset += len;
 196     /* Some fields or situations may require "expert" analysis that can be
 197      * specifically highlighted. */
 198     if ( TEST_EXPERT_condition )
 199         /* value of hf_FIELDABBREV isn't what's expected */
 200         expert_add_info(pinfo, expert_ti, &ei_PROTOABBREV_EXPERTABBREV);
 201
 202     /* Continue adding tree items to process the packet here... */
 203
 204     /* If this protocol has a sub-dissector call it here, see section 1.8 of
 205      * README.dissector for more information. */
 206
 207     /* Return the amount of data this dissector was able to dissect (which may
 208      * or may not be the total captured packet as we return here). */
 209     return tvb_captured_length(tvb);
 210 }
 211
 212 /* Register the protocol with Wireshark.
 213  *
 214  * This format is required because a script is used to build the C function that
 215  * calls all the protocol registration.
 216  */
 217 void
 218 proto_register_PROTOABBREV(void)
 219 {
 220     module_t        *PROTOABBREV_module;
 221     expert_module_t *expert_PROTOABBREV;
 222
 223     /* Setup list of header fields  See Section 1.5 of README.dissector for
 224      * details. */
 225     static hf_register_info hf[] = {
 226         { &hf_FIELDABBREV,
 227           { "FIELDNAME", "FIELDFILTERNAME",
 228             FT_FIELDTYPE, FIELDDISPLAY, FIELDCONVERT, BITMASK,
 229             "FIELDDESCR", HFILL }
 230         }
 231     };
 232
 233     /* Setup protocol subtree array */
 234     static int *ett[] = {
 235         &ett_PROTOABBREV
 236     };
 237
 238     /* Setup protocol expert items */
 239     static ei_register_info ei[] = {
 240         { &ei_PROTOABBREV_EXPERTABBREV,
 241           { "PROTOABBREV.EXPERTABBREV", PI_GROUP, PI_SEVERITY,
 242             "EXPERTDESCR", EXPFILL }
 243         }
 244     };
 245
 246     /* Register the protocol name and description */
 247     proto_PROTOABBREV = proto_register_protocol("PROTONAME", "PROTOSHORTNAME", "PROTOFILTERNAME");
 248
 249     /* Required function calls to register the header fields and subtrees */
 250     proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
 251     proto_register_subtree_array(ett, array_length(ett));
 252
 253     /* Required function calls to register expert items */
 254     expert_PROTOABBREV = expert_register_protocol(proto_PROTOABBREV);
 255     expert_register_field_array(expert_PROTOABBREV, ei, array_length(ei));
 256
 257     /* Use register_dissector() here so that the dissector can be
 258      * found by name by other protocols, by Lua, by Export PDU,
 259      * by custom User DLT dissection, etc. Some protocols may require
 260      * multiple uniquely named dissectors that behave differently
 261      * depending on the caller, e.g. over TCP directly vs over TLS.
 262      */
 263     PROTOABBREV_handle = register_dissector("PROTOABBREV", dissect_PROTOABBREV,
 264             proto_PROTOABBREV);
 265
 266     PROTOABBREV_tls_handle = register_dissector("PROTOABBREV.tls",
 267             dissect_PROTOABBREV_tls, proto_PROTOABBREV);
 268
 269     /* Register a preferences module (see section 2.6 of README.dissector
 270      * for more details). Registration of a prefs callback is not required
 271      * if there are no preferences that affect protocol registration (an example
 272      * of a preference that would affect registration is a port preference).
 273      * If the prefs callback is not needed, use NULL instead of
 274      * proto_reg_handoff_PROTOABBREV in the following.
 275      */
 276     PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV,
 277             proto_reg_handoff_PROTOABBREV);
 278
 279     /* Register a preferences module under the preferences subtree.
 280      * Only use this function instead of prefs_register_protocol (above) if you
 281      * want to group preferences of several protocols under one preferences
 282      * subtree.
 283      *
 284      * Argument subtree identifies grouping tree node name, several subnodes can
 285      * be specified using slash '/' (e.g. "OSI/X.500" - protocol preferences
 286      * will be accessible under Protocols->OSI->X.500-><PROTOSHORTNAME>
 287      * preferences node.
 288      */
 289     PROTOABBREV_module = prefs_register_protocol_subtree(const char *subtree,
 290             proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV);
 291
 292     /* Register a simple example preference */
 293     prefs_register_bool_preference(PROTOABBREV_module, "show_hex",
 294             "Display numbers in Hex",
 295             "Enable to display numerical values in hexadecimal.",
 296             &pref_hex);
 297
 298     /* Register an example port preference */
 299     prefs_register_uint_preference(PROTOABBREV_module, "tls.port", "PROTOABBREV TLS Port",
 300             " PROTOABBREV TLS port if other than the default",
 301             10, &tls_port_pref);
 302
 303 }
 304
 305 /* If this dissector uses sub-dissector registration add a registration routine.
 306  * This exact format is required because a script is used to find these
 307  * routines and create the code that calls these routines.
 308  *
 309  * If this function is registered as a prefs callback (see
 310  * prefs_register_protocol above) this function is also called by Wireshark's
 311  * preferences manager whenever "Apply" or "OK" are pressed. In that case, it
 312  * should accommodate being called more than once by use of the static
 313  * 'initialized' variable included below.
 314  *
 315  * This form of the reg_handoff function is used if you perform registration
 316  * functions which are dependent upon prefs. See below this function for a
 317  * simpler form which can be used if there are no prefs-dependent registration
 318  * functions.
 319  */
 320 void
 321 proto_reg_handoff_PROTOABBREV(void)
 322 {
 323     static bool initialized = false;
 324     static int current_tls_port_pref;
 325
 326     if (!initialized) {
 327         /* Simple port preferences like TCP can be registered as automatic
 328          * Decode As preferences.
 329          */
 330         dissector_add_uint_range_with_preference("tcp.port", PROTOABBREV_TCP_PORTS, PROTOABBREV_handle);
 331
 332         initialized = true;
 333     } else {
 334         /* If you perform registration functions which are dependent upon
 335          * prefs then you should de-register everything which was associated
 336          * with the previous settings and re-register using the new prefs
 337          * settings here. In general this means you need to keep track of
 338          * the value the preference had at the time you registered, which
 339          * can be saved using local statics in this function (proto_reg_handoff).
 340          */
 341         ssl_dissector_delete(current_tls_port_pref, PROTOABBREV_tls_handle);
 342     }
 343
 344     /* Some port preferences, like TLS, are more complicated and cannot
 345      * be done with auto preferences, because the TCP dissector has to call
 346      * TLS for the particular port as well as TLS calling this dissector.
 347      */
 348     ssl_dissector_add(tls_port_pref, PROTOABBREV_tls_handle);
 349     current_tls_port = tls_port_pref;
 350     /* Some protocols dissect packets going to the server port differently
 351      * than packets coming from the server port. The current Decode As
 352      * value can be retrieved here. Note that auto preferences are always
 353      * a range, even if registered with dissector_add_uint_with_preference.
 354      */
 355     tcp_port_range = prefs_get_range_value("PROTOABBREV", "tcp.port");
 356 }
 357
 358 #if 0
 359
 360 /* Simpler form of proto_reg_handoff_PROTOABBREV which can be used if there are
 361  * no prefs-dependent registration function calls. */
 362 void
 363 proto_reg_handoff_PROTOABBREV(void)
 364 {
 365     dissector_add_uint_range_with_preference("tcp.port", PROTOABBREV_TCP_PORTS, PROTOABBREV_handle);
 366 }
 367 #endif
 368
 369 /*
 370  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 371  *
 372  * Local variables:
 373  * c-basic-offset: 4
 374  * tab-width: 8
 375  * indent-tabs-mode: nil
 376  * End:
 377  *
 378  * vi: set shiftwidth=4 tabstop=8 expandtab:
 379  * :indentSize=4:tabSize=8:noTabs=true:
 380  */