epan/dissectors/packet-soupbintcp.c

   1 /* packet-soupbintcp.c
   2  * Routines for SoupBinTCP 3.0 protocol dissection
   3  * Copyright 2013 David Arnold <davida@pobox.com>
   4  *
   5  * $Id$
   6  *
   7  * Wireshark - Network traffic analyzer
   8  * By Gerald Combs <gerald@wireshark.org>
   9  * Copyright 1998 Gerald Combs
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * as published by the Free Software Foundation; either version 2
  14  * of the License, or (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, write to the
  23  *   Free Software Foundation, Inc.,
  24  *   51 Franklin Street, Fifth Floor,
  25  *   Boston, MA 02110-1301 USA.
  26  */
  27
  28 /*
  29  * SoupBinTCP is a framing protocol published and used by NASDAQ to
  30  * encapsulate both market data (ITCH) and order entry (OUCH)
  31  * protocols.  It is derived from the original SOUP protocol, which
  32  * was ASCII-based, and relied on an EOL indicator as a message
  33  * boundary.
  34  *
  35  * SoupBinTCP was introduced with OUCH-4.0 / ITCH-4.0 when those
  36  * protocols also switched to using a binary representation for
  37  * numerical values.
  38  *
  39  * The SOUP/SoupBinTCP protocols are also commonly used by other
  40  * financial exchanges, although frequently they are more SOUP-like
  41  * than exactly the same.  This dissector doesn't attempt to support
  42  * any other SOUP-like variants; I think it's probably better to have
  43  * separate (if similar) dissectors for them.
  44  *
  45  * The only really complexity in the protocol is the message sequence
  46  * numbering.  See the comments below for an explanation of how it is
  47  * handled.
  48  *
  49  * Specifications are available from NASDAQ's website, although the
  50  * links to find them tend to move around over time.  At the time of
  51  * writing the correct URL is:
  52  *
  53  * http://www.nasdaqtrader.com/content/technicalsupport/specifications/dataproducts/soupbintcp.pdf
  54  *
  55  */
  56
  57 #include "config.h"
  58
  59 #include <epan/conversation.h>
  60 #include <epan/packet.h>
  61 #include <epan/prefs.h>
  62 #include <epan/wmem/wmem.h>
  63
  64 /* For tcp_dissect_pdus() */
  65 #include "packet-tcp.h"
  66
  67 void proto_register_soupbintcp(void);
  68 void proto_reg_handoff_soupbintcp(void);
  69
  70 /** Session data stored in the conversation */
  71 struct conv_data {
  72     /** Next expected sequence number
  73      *
  74      * Set by the Login Accepted packet, and then updated for each
  75      * subsequent Sequenced Data packet during dissection. */
  76     guint next_seq;
  77 };
  78
  79
  80 /** Per-PDU data, stored in the frame's private data pointer */
  81 struct pdu_data {
  82     /** Sequence number for this PDU */
  83     guint seq_num;
  84 };
  85
  86
  87 /** Packet names, indexed by message type code value */
  88 static const value_string pkt_type_val[] = {
  89     { '+', "Debug Packet" },
  90     { 'A', "Login Accepted" },
  91     { 'H', "Server Heartbeat" },
  92     { 'J', "Login Rejected" },
  93     { 'L', "Login Request" },
  94     { 'O', "Logout Request" },
  95     { 'R', "Client Heartbeat" },
  96     { 'S', "Sequenced Data" },
  97     { 'U', "Unsequenced Data" },
  98     { 'Z', "End of Session" },
  99     { 0, NULL }
 100 };
 101
 102
 103 /** Login reject reasons, indexed by code value */
 104 static const value_string reject_code_val[] = {
 105     { 'A', "Not authorized" },
 106     { 'S', "Session not available" },
 107     { 0, NULL }
 108 };
 109
 110
 111 /* Initialize the protocol and registered fields */
 112 static int proto_soupbintcp = -1;
 113 static dissector_handle_t soupbintcp_handle;
 114 static heur_dissector_list_t heur_subdissector_list;
 115
 116 /* Preferences */
 117 static gboolean soupbintcp_desegment = TRUE;
 118 static range_t *global_soupbintcp_range = NULL;
 119 static range_t *soupbintcp_range = NULL;
 120
 121 /* Initialize the subtree pointers */
 122 static gint ett_soupbintcp = -1;
 123
 124 /* Header field formatting */
 125 static int hf_soupbintcp_packet_length = -1;
 126 static int hf_soupbintcp_packet_type = -1;
 127 static int hf_soupbintcp_message = -1;
 128 static int hf_soupbintcp_text = -1;
 129 static int hf_soupbintcp_username = -1;
 130 static int hf_soupbintcp_password = -1;
 131 static int hf_soupbintcp_session = -1;
 132 static int hf_soupbintcp_seq_num = -1;
 133 static int hf_soupbintcp_next_seq_num = -1;
 134 static int hf_soupbintcp_req_seq_num = -1;
 135 static int hf_soupbintcp_reject_code = -1;
 136
 137
 138 /** Format the display of the packet type code
 139  *
 140  * This function is called via BASE_CUSTOM, and displays the packet
 141  * type code as a character like it is in the specification, rather
 142  * than using BASE_DEC which shows it as an integer value. */
 143 static void
 144 format_packet_type(
 145     gchar *buf,
 146     guint32 value)
 147 {
 148     g_snprintf(buf, ITEM_LABEL_LENGTH,
 149                "%s (%c)",
 150                val_to_str(value, pkt_type_val, "Unknown packet"),
 151                (char)(value & 0xff));
 152 }
 153
 154
 155 /** Format the display of the login rejection reason code
 156  *
 157  * This function is called via BASE_CUSTOM, and displays the login
 158  * rejection reason code as a character like it is in the
 159  * specification, rather than using BASE_DEC which show it as an
 160  * integer value. */
 161 static void
 162 format_reject_code(
 163     gchar *buf,
 164     guint32 value)
 165 {
 166     g_snprintf(buf, ITEM_LABEL_LENGTH,
 167                "%s (%c)",
 168                val_to_str(value, reject_code_val, "Unknown reject code"),
 169                (char)(value & 0xff));
 170 }
 171
 172
 173 /** Dissector for SoupBinTCP messages */
 174 static void
 175 dissect_soupbintcp_common(
 176     tvbuff_t *tvb,
 177     packet_info *pinfo,
 178     proto_tree *tree)
 179 {
 180     struct conv_data *conv_data;
 181     struct pdu_data *pdu_data;
 182     tvbuff_t *sub_tvb = NULL;
 183     const char *pkt_name;
 184     const char *tmp_buf;
 185     proto_item *ti;
 186     proto_tree *soupbintcp_tree = NULL;
 187     conversation_t *conv = NULL;
 188     guint16 expected_len;
 189     guint8 pkt_type;
 190     gint offset = 0;
 191     guint this_seq = 0, next_seq;
 192
 193     /* Get the 16-bit big-endian SOUP packet length */
 194     expected_len = tvb_get_ntohs(tvb, 0);
 195
 196     /* Get the 1-byte SOUP message type */
 197     pkt_type = tvb_get_guint8(tvb, 2);
 198
 199     /* Since we use the packet name a few times, get and save that value */
 200     pkt_name = val_to_str(pkt_type, pkt_type_val, "Unknown (%u)");
 201
 202     /* Set the protocol name in the summary display */
 203     col_set_str(pinfo->cinfo, COL_PROTOCOL, "SoupBinTCP");
 204
 205     /* Set the packet name in the info column */
 206     col_add_str(pinfo->cinfo, COL_INFO, pkt_name);
 207
 208     /* Sequence number tracking
 209      *
 210      * SOUP does not number packets from client to server (the server
 211      * acknowledges all important messages, so the client should use
 212      * the acks to figure out if the server received the message, and
 213      * otherwise resend it).
 214      *
 215      * Packets from server to client are numbered, but it's implicit.
 216      * The Login Accept packet contains the next sequence number that
 217      * the server will send, and the client needs to count the
 218      * Sequenced Data packets that it receives to know what their
 219      * sequence numbers are.
 220      *
 221      * So, we grab the next sequence number from the Login Acceptance
 222      * packet, and save it in a conversation_t we associate with the
 223      * TCP session.  Then, for each Sequenced Data packet we receive,
 224      * the first time it's processed (when PINFO_FD_VISITED() is
 225      * false), we write it into the PDU's frame's private data pointer
 226      * and increment the saved sequence number (in the conversation_t).
 227      *
 228      * If the visited flag is true, then we've dissected this packet
 229      * already, and so we can fetch the sequence number from the
 230      * frame's private data area.
 231      *
 232      * In either case, if there's any problem, we report zero as the
 233      * sequence number, and try to continue dissecting. */
 234
 235     /* If first dissection of Login Accept, save sequence number */
 236     if (pkt_type == 'A' && !PINFO_FD_VISITED(pinfo)) {
 237         tmp_buf = tvb_get_string(wmem_packet_scope(), tvb, 13, 20);
 238         next_seq = atoi(tmp_buf);
 239
 240         /* Create new conversation for this session */
 241         conv = conversation_new(PINFO_FD_NUM(pinfo),
 242                                 &pinfo->src,
 243                                 &pinfo->dst,
 244                                 pinfo->ptype,
 245                                 pinfo->srcport,
 246                                 pinfo->destport,
 247                                 0);
 248
 249         /* Store starting sequence number for session's packets */
 250         conv_data = (struct conv_data *)wmem_alloc(wmem_file_scope(), sizeof(struct conv_data));
 251         conv_data->next_seq = next_seq;
 252         conversation_add_proto_data(conv, proto_soupbintcp, conv_data);
 253     }
 254
 255     /* Handle sequence numbering for a Sequenced Data packet */
 256     if (pkt_type == 'S') {
 257         if (!PINFO_FD_VISITED(pinfo)) {
 258             /* Get next expected sequence number from conversation */
 259             conv = find_conversation(PINFO_FD_NUM(pinfo),
 260                                      &pinfo->src,
 261                                      &pinfo->dst,
 262                                      pinfo->ptype,
 263                                      pinfo->srcport,
 264                                      pinfo->destport,
 265                                      0);
 266             if (!conv) {
 267                 this_seq = 0;
 268             } else {
 269                 conv_data = (struct conv_data *)conversation_get_proto_data(conv,
 270                                                         proto_soupbintcp);
 271                 if (conv_data) {
 272                     this_seq = conv_data->next_seq++;
 273                 } else {
 274                     this_seq = 0;
 275                 }
 276
 277                 pdu_data = (struct pdu_data *)wmem_alloc(
 278                     wmem_file_scope(),
 279                     sizeof(struct pdu_data));
 280                 pdu_data->seq_num = this_seq;
 281                 p_add_proto_data(pinfo->fd, proto_soupbintcp, 0, pdu_data);
 282             }
 283         } else {
 284             pdu_data = (struct pdu_data *)p_get_proto_data(
 285                 pinfo->fd,
 286                 proto_soupbintcp, 0);
 287             if (pdu_data) {
 288                 this_seq = pdu_data->seq_num;
 289             } else {
 290                 this_seq = 0;
 291             }
 292         }
 293
 294         col_append_fstr(pinfo->cinfo, COL_INFO, ", SeqNum = %u", this_seq);
 295     }
 296
 297     if (tree) {
 298         /* Create sub-tree for SoupBinTCP details */
 299         ti = proto_tree_add_item(tree,
 300                                  proto_soupbintcp,
 301                                  tvb, 0, -1, FALSE);
 302
 303         soupbintcp_tree = proto_item_add_subtree(ti, ett_soupbintcp);
 304
 305         /* Append the packet name to the sub-tree item */
 306         proto_item_append_text(ti, ", %s", pkt_name);
 307
 308         /* Length */
 309         proto_tree_add_item(soupbintcp_tree,
 310                             hf_soupbintcp_packet_length,
 311                             tvb, offset, 2, ENC_BIG_ENDIAN);
 312         offset += 2;
 313
 314         /* Type */
 315         proto_tree_add_item(soupbintcp_tree,
 316                             hf_soupbintcp_packet_type,
 317                             tvb, offset, 1, ENC_BIG_ENDIAN);
 318         offset += 1;
 319
 320         switch (pkt_type) {
 321         case '+': /* Debug Message */
 322             proto_tree_add_item(soupbintcp_tree,
 323                                 hf_soupbintcp_text,
 324                                 tvb, offset, expected_len - 1, ENC_ASCII|ENC_NA);
 325             break;
 326
 327         case 'A': /* Login Accept */
 328             proto_tree_add_item(soupbintcp_tree,
 329                                 hf_soupbintcp_session,
 330                                 tvb, offset, 10, ENC_ASCII|ENC_NA);
 331             offset += 10;
 332
 333             tmp_buf = tvb_get_string(wmem_packet_scope(), tvb, offset, 20);
 334             proto_tree_add_string_format_value(soupbintcp_tree,
 335                                                hf_soupbintcp_next_seq_num,
 336                                                tvb, offset, 20,
 337                                                "X", "%d", atoi(tmp_buf));
 338             break;
 339
 340         case 'J': /* Login Reject */
 341             proto_tree_add_item(soupbintcp_tree,
 342                                 hf_soupbintcp_reject_code,
 343                                 tvb, offset, 1, ENC_BIG_ENDIAN);
 344             break;
 345
 346         case 'U': /* Unsequenced Data */
 347             /* Display handled by sub-dissector */
 348             break;
 349
 350         case 'S': /* Sequenced Data */
 351             proto_item_append_text(ti, ", SeqNum=%u", this_seq);
 352             proto_tree_add_string_format_value(soupbintcp_tree,
 353                                                hf_soupbintcp_seq_num,
 354                                                tvb, offset, 0,
 355                                                "X",
 356                                                "%u (Calculated)",
 357                                                this_seq);
 358
 359             /* Display handled by sub-dissector */
 360             break;
 361
 362         case 'L': /* Login Request */
 363             proto_tree_add_item(soupbintcp_tree,
 364                                 hf_soupbintcp_username,
 365                                 tvb, offset, 6, ENC_ASCII|ENC_NA);
 366             offset += 6;
 367
 368             proto_tree_add_item(soupbintcp_tree,
 369                                 hf_soupbintcp_password,
 370                                 tvb, offset, 10, ENC_ASCII|ENC_NA);
 371             offset += 10;
 372
 373             proto_tree_add_item(soupbintcp_tree,
 374                                 hf_soupbintcp_session,
 375                                 tvb, offset, 10, ENC_ASCII|ENC_NA);
 376             offset += 10;
 377
 378             tmp_buf = tvb_get_string(wmem_packet_scope(), tvb, offset, 20);
 379             proto_tree_add_string_format_value(soupbintcp_tree,
 380                                                hf_soupbintcp_req_seq_num,
 381                                                tvb, offset, 20,
 382                                                "X", "%d", atoi(tmp_buf));
 383             break;
 384
 385         case 'H': /* Server Heartbeat */
 386             break;
 387
 388         case 'O': /* Logout Request */
 389             break;
 390
 391         case 'R': /* Client Heartbeat */
 392             break;
 393
 394         case 'Z': /* End of Session */
 395             break;
 396
 397         default:
 398             /* Unknown */
 399             proto_tree_add_item(tree,
 400                                 hf_soupbintcp_message,
 401                                 tvb, offset, -1, ENC_ASCII|ENC_NA);
 402             break;
 403         }
 404     }
 405
 406     /* Call sub-dissector for encapsulated data */
 407     if (pkt_type == 'S' || pkt_type == 'U') {
 408         /* Sub-dissector tvb starts at 3 (length (2) + pkt_type (1)) */
 409         sub_tvb = tvb_new_subset_remaining(tvb, 3);
 410
 411         /* If this packet is part of a conversation, call dissector
 412          * for the conversation if available */
 413         if (try_conversation_dissector(&pinfo->dst, &pinfo->src, pinfo->ptype,
 414                                        pinfo->srcport, pinfo->destport,
 415                                        sub_tvb, pinfo, tree, NULL)) {
 416             return;
 417         }
 418
 419         /* Otherwise, try heuristic dissectors */
 420         if (dissector_try_heuristic(heur_subdissector_list,
 421                                     sub_tvb,
 422                                     pinfo,
 423                                     tree,
 424                                     NULL)) {
 425             return;
 426         }
 427
 428         /* Otherwise, give up, and just print the bytes in hex */
 429         if (tree) {
 430             proto_tree_add_item(soupbintcp_tree,
 431                                 hf_soupbintcp_message,
 432                                 sub_tvb, 0, -1,
 433                                 ENC_ASCII|ENC_NA);
 434         }
 435     }
 436 }
 437
 438
 439 /** Return the size of the PDU in @p tvb, starting at @p offset */
 440 static guint
 441 get_soupbintcp_pdu_len(
 442     packet_info *pinfo _U_,
 443     tvbuff_t *tvb,
 444     int offset)
 445 {
 446     /* Determine the length of the PDU using the SOUP header's 16-bit
 447        big-endian length (at offset zero).  We're guaranteed to get at
 448        least two bytes here because we told tcp_dissect_pdus() that we
 449        needed them.  Add 2 to the retrieved value, because the SOUP
 450        length doesn't include the length field itself. */
 451     return (guint)tvb_get_ntohs(tvb, offset) + 2;
 452 }
 453
 454
 455 /** Dissect a possibly-reassembled TCP PDU */
 456 static int
 457 dissect_soupbintcp_tcp_pdu(
 458     tvbuff_t *tvb,
 459     packet_info *pinfo,
 460     proto_tree *tree, void* data _U_)
 461 {
 462     col_set_str(pinfo->cinfo, COL_PROTOCOL, "SoupBinTCP");
 463     dissect_soupbintcp_common(tvb, pinfo, tree);
 464     return tvb_length(tvb);
 465 }
 466
 467
 468 /** Dissect a TCP segment containing SoupBinTCP data */
 469 static int
 470 dissect_soupbintcp_tcp(
 471     tvbuff_t *tvb,
 472     packet_info *pinfo,
 473     proto_tree *tree, void* data)
 474 {
 475     tcp_dissect_pdus(tvb, pinfo, tree,
 476                      soupbintcp_desegment, 2,
 477                      get_soupbintcp_pdu_len,
 478                      dissect_soupbintcp_tcp_pdu, data);
 479     return tvb_length(tvb);
 480 }
 481
 482 static void
 483 soupbintcp_prefs(void)
 484 {
 485         dissector_delete_uint_range("tcp.port", soupbintcp_range, soupbintcp_handle);
 486     g_free(soupbintcp_range);
 487     soupbintcp_range = range_copy(global_soupbintcp_range);
 488         dissector_add_uint_range("tcp.port", soupbintcp_range, soupbintcp_handle);
 489 }
 490
 491
 492 void
 493 proto_register_soupbintcp(void)
 494 {
 495     /* Setup list of header fields  See Section 1.6.1 for details*/
 496     static hf_register_info hf[] = {
 497
 498         { &hf_soupbintcp_packet_length,
 499           { "Packet Length", "soupbintcp.packet_length",
 500             FT_UINT16, BASE_DEC, NULL, 0x0,
 501             "Packet length, in bytes, NOT including these two bytes.",
 502             HFILL }},
 503
 504         { &hf_soupbintcp_packet_type,
 505           { "Packet Type", "soupbintcp.packet_type",
 506             FT_UINT8, BASE_CUSTOM, format_packet_type, 0x0,
 507             "Message type code",
 508             HFILL }},
 509
 510         { &hf_soupbintcp_reject_code,
 511           { "Login Reject Code", "soupbintcp.reject_code",
 512             FT_UINT8, BASE_CUSTOM, format_reject_code, 0x0,
 513             "Login reject reason code",
 514             HFILL }},
 515
 516         { &hf_soupbintcp_message,
 517           { "Message", "soupbintcp.message",
 518             FT_BYTES, BASE_NONE, NULL, 0x0,
 519             "Content of SoupBinTCP frame",
 520             HFILL }},
 521
 522         { &hf_soupbintcp_text,
 523           { "Debug Text", "soupbintcp.text",
 524             FT_STRING, BASE_NONE, NULL, 0x0,
 525             "Free-form, human-readable text",
 526             HFILL }},
 527
 528         { &hf_soupbintcp_username,
 529           { "User Name", "soupbintcp.username",
 530             FT_STRING, BASE_NONE, NULL, 0x0,
 531             "User's login name",
 532             HFILL }},
 533
 534         { &hf_soupbintcp_password,
 535           { "Password", "soupbintcp.password",
 536             FT_STRING, BASE_NONE, NULL, 0x0,
 537             "User's login password",
 538             HFILL }},
 539
 540         { &hf_soupbintcp_session,
 541           { "Session", "soupbintcp.session",
 542             FT_STRING, BASE_NONE, NULL, 0x0,
 543             "Session identifier, or send all spaces to log into the currently "
 544             "active session",
 545             HFILL }},
 546
 547         { &hf_soupbintcp_seq_num,
 548           { "Sequence number", "soupbintcp.seq_num",
 549             FT_STRING, BASE_NONE, NULL, 0x0,
 550             "Calculated sequence number for this message",
 551             HFILL }},
 552
 553         { &hf_soupbintcp_next_seq_num,
 554           { "Next sequence number", "soupbintcp.next_seq_num",
 555             FT_STRING, BASE_NONE, NULL, 0x0,
 556             "Sequence number of next Sequenced Data message to be delivered",
 557             HFILL }},
 558
 559         { &hf_soupbintcp_req_seq_num,
 560           { "Requested sequence number", "soupbintcp.req_seq_num",
 561             FT_STRING, BASE_NONE, NULL, 0x0,
 562             "Request to begin (re)transmission of Sequenced Data at this "
 563             "sequence number, or, if zero, to begin transmission with the "
 564             "next message generated",
 565             HFILL }}
 566     };
 567
 568     /* Setup protocol subtree array */
 569     static gint *ett[] = {
 570         &ett_soupbintcp
 571     };
 572
 573     module_t *soupbintcp_module;
 574
 575     /* Register the protocol name and description */
 576     proto_soupbintcp
 577         = proto_register_protocol("SoupBinTCP", "SoupBinTCP", "soupbintcp");
 578
 579     /* Required function calls to register the header fields and
 580        subtrees used */
 581     proto_register_field_array(proto_soupbintcp, hf, array_length(hf));
 582     proto_register_subtree_array(ett, array_length(ett));
 583
 584     soupbintcp_module
 585         = prefs_register_protocol(proto_soupbintcp,
 586                                   soupbintcp_prefs);
 587
 588     prefs_register_bool_preference(
 589         soupbintcp_module,
 590         "desegment",
 591         "Reassemble SoupBinTCP messages spanning multiple TCP segments",
 592         "Whether the SoupBinTCP dissector should reassemble messages "
 593         "spanning multiple TCP segments.",
 594         &soupbintcp_desegment);
 595
 596     prefs_register_range_preference(
 597         soupbintcp_module,
 598         "tcp.port",
 599         "TCP Ports",
 600         "TCP Ports range",
 601         &global_soupbintcp_range,
 602         65535);
 603
 604     soupbintcp_range = range_empty();
 605
 606     register_heur_dissector_list("soupbintcp", &heur_subdissector_list);
 607 }
 608
 609
 610 /* If this dissector uses sub-dissector registration add a
 611    registration routine.  This format is required because a script is
 612    used to find these routines and create the code that calls these
 613    routines.
 614 */
 615 void
 616 proto_reg_handoff_soupbintcp(void)
 617 {
 618     soupbintcp_handle = new_create_dissector_handle(dissect_soupbintcp_tcp,
 619                                                 proto_soupbintcp);
 620
 621     /* For "decode-as" */
 622     dissector_add_handle("tcp.port", soupbintcp_handle);
 623 }
 624
 625
 626 /*
 627  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 628  *
 629  * Local variables:
 630  * c-basic-offset: 4
 631  * tab-width: 8
 632  * indent-tabs-mode: nil
 633  * End:
 634  *
 635  * vi: set shiftwidth=4 tabstop=8 expandtab:
 636  * :indentSize=4:tabSize=8:noTabs=true:
 637  */