2021-11-26 03:31:05 +00:00
|
|
|
/** @file
|
2013-05-05 19:36:53 +00:00
|
|
|
* Routines for exported_pdu dissection
|
|
|
|
|
* Copyright 2013, Anders Broman <anders-broman@ericsson.com>
|
|
|
|
|
*
|
|
|
|
|
* Wireshark - Network traffic analyzer
|
|
|
|
|
* By Gerald Combs <gerald@wireshark.org>
|
|
|
|
|
* Copyright 1998 Gerald Combs
|
|
|
|
|
*
|
2018-02-08 16:59:17 +00:00
|
|
|
* SPDX-License-Identifier: GPL-2.0-or-later
|
2013-05-05 19:36:53 +00:00
|
|
|
*/
|
|
|
|
|
|
2013-10-15 20:14:47 +00:00
|
|
|
#ifndef EXPORTED_PDU_H
|
|
|
|
|
#define EXPORTED_PDU_H
|
|
|
|
|
|
2014-06-19 00:42:47 +00:00
|
|
|
#include "ws_symbol_export.h"
|
2017-09-05 16:18:00 +00:00
|
|
|
#include "ws_attributes.h"
|
2014-06-19 00:42:47 +00:00
|
|
|
|
2013-05-05 19:36:53 +00:00
|
|
|
#include <glib.h>
|
|
|
|
|
|
2017-12-08 08:30:55 +00:00
|
|
|
#include <epan/tvbuff.h>
|
|
|
|
|
#include <epan/packet_info.h>
|
|
|
|
|
|
2021-08-20 09:17:14 +00:00
|
|
|
#include <wsutil/exported_pdu_tlvs.h>
|
|
|
|
|
|
2014-06-19 00:42:47 +00:00
|
|
|
#ifdef __cplusplus
|
|
|
|
|
extern "C" {
|
|
|
|
|
#endif /* __cplusplus */
|
|
|
|
|
|
2014-04-17 23:26:50 +00:00
|
|
|
/*
|
|
|
|
|
* Define different common tap names to extract PDUs at different layers,
|
|
|
|
|
* otherwise one packet may be exported several times at different layers
|
|
|
|
|
* if all taps are run.
|
2013-05-20 17:48:09 +00:00
|
|
|
*/
|
2013-06-18 23:01:46 +00:00
|
|
|
#define EXPORT_PDU_TAP_NAME_LAYER_3 "OSI layer 3"
|
2016-07-24 01:25:05 +00:00
|
|
|
#define EXPORT_PDU_TAP_NAME_LAYER_4 "OSI layer 4"
|
2013-06-18 23:01:46 +00:00
|
|
|
#define EXPORT_PDU_TAP_NAME_LAYER_7 "OSI layer 7"
|
2014-06-19 00:42:47 +00:00
|
|
|
|
|
|
|
|
/* To add dynamically an export name, call the following function
|
|
|
|
|
It returns the registered tap */
|
|
|
|
|
WS_DLL_PUBLIC gint register_export_pdu_tap(const char *name);
|
2021-08-28 00:39:07 +00:00
|
|
|
/* Same as above, but for export taps that use an encapsulation other
|
|
|
|
|
* than WTAP_ENCAP_WIRESHARK_UPPER_PDU */
|
|
|
|
|
WS_DLL_PUBLIC gint register_export_pdu_tap_with_encap(const char *name, gint encap);
|
2014-06-19 00:42:47 +00:00
|
|
|
WS_DLL_PUBLIC GSList *get_export_pdu_tap_list(void);
|
2013-06-18 23:01:46 +00:00
|
|
|
|
2021-08-28 00:39:07 +00:00
|
|
|
WS_DLL_PUBLIC gint export_pdu_tap_get_encap(const char* name);
|
|
|
|
|
|
2016-06-24 03:10:08 +00:00
|
|
|
/** Compute the size (in bytes) of a pdu item
|
|
|
|
|
*
|
|
|
|
|
@param pinfo Packet info that may contain data for the pdu item
|
|
|
|
|
@param data optional data of the pdu item
|
|
|
|
|
@return the size of the pdu item
|
|
|
|
|
*/
|
|
|
|
|
typedef int (*exp_pdu_get_size)(packet_info *pinfo, void* data);
|
|
|
|
|
|
|
|
|
|
/** Populate a buffer with pdu item data
|
|
|
|
|
*
|
|
|
|
|
@param pinfo Packet info that may contain data for the PDU item
|
|
|
|
|
@param data optional data of the PDU item
|
|
|
|
|
@param tlv_buffer buffer to be populated with PDU item
|
|
|
|
|
@param tlv_buffer_size size of buffer to be populated
|
|
|
|
|
@return the number of bytes populated to the buffer (typically PDU item size)
|
|
|
|
|
*/
|
|
|
|
|
typedef int (*exp_pdu_populate_data)(packet_info *pinfo, void* data, guint8 *tlv_buffer, guint32 tlv_buffer_size);
|
|
|
|
|
|
|
|
|
|
typedef struct exp_pdu_data_item
|
|
|
|
|
{
|
|
|
|
|
exp_pdu_get_size size_func;
|
|
|
|
|
exp_pdu_populate_data populate_data;
|
|
|
|
|
void* data;
|
|
|
|
|
} exp_pdu_data_item_t;
|
|
|
|
|
|
2021-08-20 09:17:14 +00:00
|
|
|
/*
|
|
|
|
|
* This struct is used as the data part of tap_queue_packet() and contains a
|
|
|
|
|
* buffer with metadata of the protocol PDU included in the tvb in the struct.
|
|
|
|
|
*
|
|
|
|
|
* The metadata is a sequence of TLVs in the format for the header of
|
|
|
|
|
* LINKTYPE_WIRESHARK_UPPER_PDU packets in pcap pcapng files.
|
|
|
|
|
*/
|
|
|
|
|
typedef struct _exp_pdu_data_t {
|
|
|
|
|
guint tlv_buffer_len;
|
|
|
|
|
guint8 *tlv_buffer;
|
|
|
|
|
guint tvb_captured_length;
|
|
|
|
|
guint tvb_reported_length;
|
|
|
|
|
tvbuff_t *pdu_tvb;
|
|
|
|
|
} exp_pdu_data_t;
|
|
|
|
|
|
2013-05-06 16:31:29 +00:00
|
|
|
/**
|
2016-06-24 03:10:08 +00:00
|
|
|
Allocates and fills the exp_pdu_data_t struct according to the list of items
|
|
|
|
|
|
|
|
|
|
The tags in the tag buffer SHOULD be added in numerical order.
|
|
|
|
|
|
|
|
|
|
@param pinfo Packet info that may contain data for the PDU items
|
|
|
|
|
@param proto_name Name of protocol that is exporting PDU
|
Dissector names are not protocol names.
A given protocol's packet format may depend, for example, on which
lower-level protocol is transporting the protocol in question. For
example, protocols that run atop both byte-stream protocols such as TCP
and TLS, and packet-oriented protocols such as UDP or DTLS, might begin
the packet with a length when running atop a byte-stream protocol, to
indicate where this packet ends and the next packet begins in the byte
stream, but not do so when running atop a packet-oriented protocol.
Dissectors can handle this in various ways:
For example, the dissector could attempt to determine the protocol over
which the packet was transported.
Unfortunately, many of those mechanisms do so by fetching data from the
packet_info structure, and many items in that structure act as global
variables, so that, for example, if there are two two PDUs for protocol
A inside a TCP segment, and the first protocol for PDU A contains a PDU
for protocol B, and protocol B's dissector, or a dissector it calls,
modifies the information in the packet_info structure so that it no
longer indicates that the parent protocol is TCP, the second PDU for
protocol A might not be correctly dissected.
Another such mechanism is to query the previous element in the layers
structure of the packet_info structure, which is a list of protocol IDs.
Unfortunately, that is not a list of earlier protocols in the protocol
stack, it's a list of earlier protocols in the dissection, which means
that, in the above example, when the second PDU for protocol A is
dissected, the list is {...,TCP,A,B,...,A}, which means that the
previous element in the list is not TCP, so, again, the second PDU for
protocol A will not be correctly dissected.
An alternative is to have multiple dissectors for the same protocol,
with the part of the protocol that's independent of the protocol
transporting the PDU being dissected by common code. Protocol B might
have an "over a byte-stream transport" dissector and an "over a packet
transport" dissector, with the first dissector being registered for use
over TCP and TLS and the other dissector being registered for use over
packet protocols. This mechanism, unlike the other mechanisms, is not
dependent on information in the packet_info structure that might be
affected by dissectors other than the one for the protocol that
transports protocol B.
Furthermore, in a LINKTYPE_WIRESHARK_UPPER_PDU pcap or pcapng packet for
protocol B, there might not be any information to indicate the protocol
that transports protocol B, so there would have to be separate
dissectors for protocol B, with separate names, so that a tag giving the
protocol name would differ for B-over-byte-stream and B-over-packets.
So:
We rename EXP_PDU_TAG_PROTO_NAME and EXP_PDU_TAG_HEUR_PROTO_NAME to
EXP_PDU_TAG_DISSECTOR_NAME and EXP_PDU_TAG_HEUR_DISSECTOR_NAME, to
emphasize that they are *not* protocol names, they are dissector names
(which has always been the case - if there's a protocol with that name,
but no dissector with that name, Wireshark will not be able to handle
the packet, as it will try to look up a dissector given that name and
fail).
We fix that exported PDU dissector to refer to those tags as dissector
names, not protocol names.
We update documentation to refer to them as DISSECTOR_NAME tags, not
PROTO_NAME tags. (If there is any documentation for this outside the
Wireshark source, it should be updated as well.)
We add comments for calls to dissector_handle_get_dissector_name() where
the dissector name is shown to the user, to indicate that it might be
that the protocol name should be used.
We update the TLS and DTLS dissectors to show the encapsulated protocol
as the string returned by dissector_handle_get_long_name(); as the
default is "Application Data", it appeaers that a descriptive name,
rather than a short API name, should be used. (We continue to use the
dissector name in debugging messages, to indicate which dissector was
called.)
2022-09-11 05:37:11 +00:00
|
|
|
@param tag_type Tag type for protocol's PDU. Must be EXP_PDU_TAG_DISSECTOR_NAME or EXP_PDU_TAG_HEUR_DISSECTOR_NAME.
|
2016-06-24 03:10:08 +00:00
|
|
|
@param items PDU items to be exported
|
|
|
|
|
@return filled exp_pdu_data_t struct
|
|
|
|
|
*/
|
|
|
|
|
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);
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
Allocates and fills the exp_pdu_data_t struct with a common list of items
|
|
|
|
|
The items that will be exported as the PDU are:
|
|
|
|
|
1. Source IP
|
|
|
|
|
2. Destintaiton IP
|
|
|
|
|
3. Port type
|
|
|
|
|
4. Source Port
|
|
|
|
|
5. Destination Port
|
|
|
|
|
6. Original frame number
|
|
|
|
|
|
|
|
|
|
@param pinfo Packet info that may contain data for the PDU items
|
Dissector names are not protocol names.
A given protocol's packet format may depend, for example, on which
lower-level protocol is transporting the protocol in question. For
example, protocols that run atop both byte-stream protocols such as TCP
and TLS, and packet-oriented protocols such as UDP or DTLS, might begin
the packet with a length when running atop a byte-stream protocol, to
indicate where this packet ends and the next packet begins in the byte
stream, but not do so when running atop a packet-oriented protocol.
Dissectors can handle this in various ways:
For example, the dissector could attempt to determine the protocol over
which the packet was transported.
Unfortunately, many of those mechanisms do so by fetching data from the
packet_info structure, and many items in that structure act as global
variables, so that, for example, if there are two two PDUs for protocol
A inside a TCP segment, and the first protocol for PDU A contains a PDU
for protocol B, and protocol B's dissector, or a dissector it calls,
modifies the information in the packet_info structure so that it no
longer indicates that the parent protocol is TCP, the second PDU for
protocol A might not be correctly dissected.
Another such mechanism is to query the previous element in the layers
structure of the packet_info structure, which is a list of protocol IDs.
Unfortunately, that is not a list of earlier protocols in the protocol
stack, it's a list of earlier protocols in the dissection, which means
that, in the above example, when the second PDU for protocol A is
dissected, the list is {...,TCP,A,B,...,A}, which means that the
previous element in the list is not TCP, so, again, the second PDU for
protocol A will not be correctly dissected.
An alternative is to have multiple dissectors for the same protocol,
with the part of the protocol that's independent of the protocol
transporting the PDU being dissected by common code. Protocol B might
have an "over a byte-stream transport" dissector and an "over a packet
transport" dissector, with the first dissector being registered for use
over TCP and TLS and the other dissector being registered for use over
packet protocols. This mechanism, unlike the other mechanisms, is not
dependent on information in the packet_info structure that might be
affected by dissectors other than the one for the protocol that
transports protocol B.
Furthermore, in a LINKTYPE_WIRESHARK_UPPER_PDU pcap or pcapng packet for
protocol B, there might not be any information to indicate the protocol
that transports protocol B, so there would have to be separate
dissectors for protocol B, with separate names, so that a tag giving the
protocol name would differ for B-over-byte-stream and B-over-packets.
So:
We rename EXP_PDU_TAG_PROTO_NAME and EXP_PDU_TAG_HEUR_PROTO_NAME to
EXP_PDU_TAG_DISSECTOR_NAME and EXP_PDU_TAG_HEUR_DISSECTOR_NAME, to
emphasize that they are *not* protocol names, they are dissector names
(which has always been the case - if there's a protocol with that name,
but no dissector with that name, Wireshark will not be able to handle
the packet, as it will try to look up a dissector given that name and
fail).
We fix that exported PDU dissector to refer to those tags as dissector
names, not protocol names.
We update documentation to refer to them as DISSECTOR_NAME tags, not
PROTO_NAME tags. (If there is any documentation for this outside the
Wireshark source, it should be updated as well.)
We add comments for calls to dissector_handle_get_dissector_name() where
the dissector name is shown to the user, to indicate that it might be
that the protocol name should be used.
We update the TLS and DTLS dissectors to show the encapsulated protocol
as the string returned by dissector_handle_get_long_name(); as the
default is "Application Data", it appeaers that a descriptive name,
rather than a short API name, should be used. (We continue to use the
dissector name in debugging messages, to indicate which dissector was
called.)
2022-09-11 05:37:11 +00:00
|
|
|
@param tag_type Tag type for protocol's PDU. Must be EXP_PDU_TAG_DISSECTOR_NAME, EXP_PDU_TAG_HEUR_DISSECTOR_NAME or EXP_PDU_TAG_DISSECTOR_TABLE_NAME
|
2016-06-24 03:10:08 +00:00
|
|
|
@param proto_name Name of protocol that is exporting PDU
|
|
|
|
|
@return filled exp_pdu_data_t struct
|
|
|
|
|
*/
|
|
|
|
|
WS_DLL_PUBLIC exp_pdu_data_t *export_pdu_create_common_tags(packet_info *pinfo, const char *proto_name, guint16 tag_type);
|
|
|
|
|
|
2016-07-24 01:25:05 +00:00
|
|
|
WS_DLL_PUBLIC int exp_pdu_data_dissector_table_num_value_size(packet_info *pinfo, void* data);
|
|
|
|
|
WS_DLL_PUBLIC int exp_pdu_data_dissector_table_num_value_populate_data(packet_info *pinfo, void* data, guint8 *tlv_buffer, guint32 buffer_size);
|
|
|
|
|
|
2016-06-24 03:10:08 +00:00
|
|
|
WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_src_ip;
|
|
|
|
|
WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_dst_ip;
|
|
|
|
|
WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_port_type;
|
|
|
|
|
WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_src_port;
|
|
|
|
|
WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_dst_port;
|
|
|
|
|
WS_DLL_PUBLIC exp_pdu_data_item_t exp_pdu_data_orig_frame_num;
|
2013-10-15 20:14:47 +00:00
|
|
|
|
2016-06-12 16:28:02 +00:00
|
|
|
extern void export_pdu_init(void);
|
|
|
|
|
|
2017-01-16 20:51:39 +00:00
|
|
|
extern void export_pdu_cleanup(void);
|
|
|
|
|
|
2014-06-19 00:42:47 +00:00
|
|
|
#ifdef __cplusplus
|
|
|
|
|
}
|
|
|
|
|
#endif /* __cplusplus */
|
2013-10-15 20:14:47 +00:00
|
|
|
|
2014-06-19 00:42:47 +00:00
|
|
|
#endif /* EXPORTED_PDU_H */
|