Wireshark  4.3.0
The Wireshark network protocol analyzer
conversation.h
Go to the documentation of this file.
1 /* conversation.h
2  * Routines for building lists of packets that are part of a "conversation"
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 __CONVERSATION_H__
12 #define __CONVERSATION_H__
13 
14 #include "ws_symbol_export.h"
15 
16 #include "packet.h" /* for conversation dissector type */
17 #include <epan/wmem_scopes.h>
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif /* __cplusplus */
22 
41 #define NO_ADDR2 0x01
42 #define NO_PORT2 0x02
43 #define NO_PORT2_FORCE 0x04
44 #define CONVERSATION_TEMPLATE 0x08
45 #define NO_PORTS 0x010
46 
51 #define NO_MASK_B 0xFFFF0000
52 #define NO_ADDR_B 0x00010000
53 #define NO_PORT_B 0x00020000
54 #define NO_PORT_X 0x00040000
55 #define NO_ANC 0x00080000
56 
58 #define USE_LAST_ENDPOINT 0x08
60 /* Types of conversations Wireshark knows about. */
61 /* XXX: There should be a way to register conversation types used only
62  * within one dissector, similar to address types, instead of changing
63  * the global typedef.
64  */
65 typedef enum {
66  CONVERSATION_NONE, /* no conversation key */
67  CONVERSATION_SCTP, /* SCTP */
68  CONVERSATION_TCP, /* TCP address/port pairs */
69  CONVERSATION_UDP, /* UDP address/port pairs */
70  CONVERSATION_DCCP, /* DCCP */
71  CONVERSATION_IPX, /* IPX sockets */
72  CONVERSATION_NCP, /* NCP connection */
73  CONVERSATION_EXCHG, /* Fibre Channel exchange */
74  CONVERSATION_DDP, /* DDP AppleTalk address/port pair */
75  CONVERSATION_SBCCS, /* FICON */
76  CONVERSATION_IDP, /* XNS IDP sockets */
77  CONVERSATION_TIPC, /* TIPC PORT */
78  CONVERSATION_USB, /* USB endpoint 0xffff means the host */
79  CONVERSATION_I2C,
80  CONVERSATION_IBQP, /* Infiniband QP number */
81  CONVERSATION_BLUETOOTH,
82  CONVERSATION_TDMOP,
83  CONVERSATION_DVBCI,
84  CONVERSATION_ISO14443,
85  CONVERSATION_ISDN, /* ISDN channel number */
86  CONVERSATION_H223, /* H.223 logical channel number */
87  CONVERSATION_X25, /* X.25 logical channel number */
88  CONVERSATION_IAX2, /* IAX2 call id */
89  CONVERSATION_DLCI, /* Frame Relay DLCI */
90  CONVERSATION_ISUP, /* ISDN User Part CIC */
91  CONVERSATION_BICC, /* BICC Circuit identifier */
92  CONVERSATION_GSMTAP,
93  CONVERSATION_IUUP,
94  CONVERSATION_DVBBBF, /* DVB Base Band Frame ISI/PLP_ID */
95  CONVERSATION_IWARP_MPA, /* iWarp MPA */
96  CONVERSATION_BT_UTP, /* BitTorrent uTP Connection ID */
97  CONVERSATION_LOG, /* Logging source */
98  CONVERSATION_LTP, /* LTP Engine ID and Session Number */
99  CONVERSATION_MCTP,
100  CONVERSATION_NVME_MI, /* NVMe management interface */
101  CONVERSATION_BP, /* Bundle Protocol endpoint IDs */
102  CONVERSATION_SNMP, /* SNMP */
103  CONVERSATION_QUIC, /* QUIC */
104  CONVERSATION_IDN,
105  CONVERSATION_IP, /* IP */
106  CONVERSATION_IPV6, /* IPv6 */
107  CONVERSATION_ETH, /* ETHERNET classic */
108  CONVERSATION_ETH_NN, /* ETHERNET deinterlaced Interface:N VLAN:N */
109  CONVERSATION_ETH_NV, /* ETHERNET deinterlaced Interface:N VLAN:Y */
110  CONVERSATION_ETH_IN, /* ETHERNET deinterlaced Interface:Y VLAN:N */
111  CONVERSATION_ETH_IV, /* ETHERNET deinterlaced Interface:Y VLAN:Y */
112  CONVERSATION_VSPC_VMOTION, /* VMware vSPC vMotion (Telnet) */
113 } conversation_type;
114 
115 /*
116  * XXX - for now, we just #define these to be the same as the
117  * corresponding CONVERSATION_ values, for backwards source
118  * compatibility.
119  *
120  * In the long term, we should make this into a separate enum,
121  * with elements corresponding to conversation types that do
122  * not have known endpoints removed.
123  */
124 /* Types of conversation endpoints Wireshark knows about. */
125 #define ENDPOINT_NONE CONVERSATION_NONE
126 #define ENDPOINT_SCTP CONVERSATION_SCTP
127 #define ENDPOINT_TCP CONVERSATION_TCP
128 #define ENDPOINT_UDP CONVERSATION_UDP
129 #define ENDPOINT_DCCP CONVERSATION_DCCP
130 #define ENDPOINT_IPX CONVERSATION_IPX
131 #define ENDPOINT_NCP CONVERSATION_NCP
132 #define ENDPOINT_EXCHG CONVERSATION_EXCHG
133 #define ENDPOINT_DDP CONVERSATION_DDP
134 #define ENDPOINT_SBCCS CONVERSATION_SBCCS
135 #define ENDPOINT_IDP CONVERSATION_IDP
136 #define ENDPOINT_TIPC CONVERSATION_TIPC
137 #define ENDPOINT_USB CONVERSATION_USB
138 #define ENDPOINT_I2C CONVERSATION_I2C
139 #define ENDPOINT_IBQP CONVERSATION_IBQP
140 #define ENDPOINT_BLUETOOTH CONVERSATION_BLUETOOTH
141 #define ENDPOINT_TDMOP CONVERSATION_TDMOP
142 #define ENDPOINT_DVBCI CONVERSATION_DVBCI
143 #define ENDPOINT_ISO14443 CONVERSATION_ISO14443
144 #define ENDPOINT_ISDN CONVERSATION_ISDN
145 #define ENDPOINT_H223 CONVERSATION_H223
146 #define ENDPOINT_X25 CONVERSATION_X25
147 #define ENDPOINT_IAX2 CONVERSATION_IAX2
148 #define ENDPOINT_DLCI CONVERSATION_DLCI
149 #define ENDPOINT_ISUP CONVERSATION_ISUP
150 #define ENDPOINT_BICC CONVERSATION_BICC
151 #define ENDPOINT_GSMTAP CONVERSATION_GSMTAP
152 #define ENDPOINT_IUUP CONVERSATION_IUUP
153 #define ENDPOINT_DVBBBF CONVERSATION_DVBBBF
154 #define ENDPOINT_IWARP_MPA CONVERSATION_IWARP_MPA
155 #define ENDPOINT_BT_UTP CONVERSATION_BT_UTP
156 #define ENDPOINT_LOG CONVERSATION_LOG
157 #define ENDPOINT_MCTP CONVERSATION_MCTP
158 #define ENDPOINT_NVME_MI CONVERSATION_NVME_MI
159 #define ENDPOINT_SNMP CONVERSATION_SNMP
160 
161 typedef conversation_type endpoint_type;
162 
166 typedef enum {
167  CE_CONVERSATION_TYPE, /* CONVERSATION_ value */
168  CE_ADDRESS, /* address */
169  CE_PORT, /* unsigned integer representing a port */
170  CE_STRING, /* string */
171  CE_UINT, /* unsigned integer not representing a port */
172  CE_UINT64, /* 64-bit unsigned integer */
173  CE_INT, /* signed integer */
174  CE_INT64, /* signed integer */
175  CE_BLOB, /* arbitrary binary data */
177 
199 typedef struct conversation_element {
201  union {
202  conversation_type conversation_type_val;
203  address addr_val;
204  unsigned int port_val;
205  const char *str_val;
206  unsigned int uint_val;
207  uint64_t uint64_val;
208  int int_val;
209  int64_t int64_val;
210  struct {
211  const uint8_t *val;
212  size_t len;
213  } blob;
214  };
216 
220 typedef struct conversation {
221  struct conversation *next;
222  struct conversation *last;
224  guint32 conv_index;
225  guint32 setup_frame;
226  /* Assume that setup_frame is also the lowest frame number for now. */
227  guint32 last_frame;
230  guint options;
233 
234 /*
235  * For some protocols, we store, in the packet_info structure, a pair
236  * of address/port endpoints, for use by code that might want to
237  * construct a conversation for that protocol.
238  *
239  * This appears to have been done in order to allow protocols to save
240  * that information *without* overwriting the addresses or ports in the
241  * packet_info structure, so that the other code that uses those values,
242  * such as the code that fills in the address and port columns in the
243  * packet summary, will pick up the values put there by protocols such
244  * as IP and UDP, rather than the values put there by protocols such as
245  * TDMoP, FCIP, TIPC, and DVB Dynamic Mode Adaptation. See commit
246  * 66b441f3d63e21949530d672bf1406dea94ed254 and issue #11340.
247  *
248  * That is set by conversation_set_conv_addr_port_endpoints().
249  *
250  * In find_conversation_pinfo() and find_or_create_conversation(), if
251  * any dissector has set this, that address/port endpoint pair is used
252  * to look up or create the conversation.
253  *
254  * Prior to 4.0, conversations identified by a single integer value
255  * (such as a circuit ID) were handled by creating a pair of address/port
256  * endpoints with null addresses, the first port equal to the integer
257  * value, the second port missing, and a port type being an ENDPOINT_
258  * type specifying the protocol for the conversation. Now we use an
259  * array of elements, with a CE_UINT value for the integer followed
260  * by a CE_CONVERSATION_TYPE value specifying the protocol for the
261  * conversation.
262  *
263  * XXX - is there any reason why we shouldn't use an array of conversation
264  * elements, with the appropriate addresses and ports, instead of this
265  * structure? It would at least simplify find_conversation_pinfo() and
266  * find_or_create_conversation().
267  */
270 
271 WS_DLL_PUBLIC const address* conversation_key_addr1(const conversation_element_t *key);
272 WS_DLL_PUBLIC guint32 conversation_key_port1(const conversation_element_t *key);
273 WS_DLL_PUBLIC const address* conversation_key_addr2(const conversation_element_t *key);
274 WS_DLL_PUBLIC guint32 conversation_key_port2(const conversation_element_t *key);
275 
279 extern void conversation_init(void);
280 
284 extern void conversation_epan_reset(void);
285 
292 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_full(const guint32 setup_frame, conversation_element_t *elements);
293 
313 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new(const guint32 setup_frame, const address *addr1, const address *addr2,
314  const conversation_type ctype, const guint32 port1, const guint32 port2, const guint options);
315 
316 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_by_id(const guint32 setup_frame, const conversation_type ctype, const guint32 id);
317 
321 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_deinterlaced(const guint32 setup_frame, const address *addr1, const address *addr2,
322  const conversation_type ctype, const guint32 port1, const guint32 port2, const guint32 anchor, const guint options);
323 
337 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_deinterlacer(const guint32 setup_frame, const address *addr1, const address *addr2,
338  const conversation_type ctype, const guint32 key1, const guint32 key2, const guint32 key3);
339 
350 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_strat(packet_info *pinfo, const conversation_type ctype, const guint options);
351 
358 WS_DLL_PUBLIC conversation_t *find_conversation_full(const guint32 frame_num, conversation_element_t *elements);
359 
407 WS_DLL_PUBLIC conversation_t *find_conversation(const guint32 frame_num, const address *addr_a, const address *addr_b,
408  const conversation_type ctype, const guint32 port_a, const guint32 port_b, const guint options);
409 
410 WS_DLL_PUBLIC conversation_t *find_conversation_deinterlaced(const guint32 frame_num, const address *addr_a, const address *addr_b,
411  const conversation_type ctype, const guint32 port_a, const guint32 port_b, const guint32 anchor, const guint options);
412 
413 WS_DLL_PUBLIC conversation_t *find_conversation_deinterlacer(const guint32 frame_num, const address *addr_a, const address *addr_b,
414  const conversation_type ctype, const guint32 key_a, const guint32 key_b, const guint32 key_c);
415 
422 
423 WS_DLL_PUBLIC conversation_t *find_conversation_by_id(const guint32 frame, const conversation_type ctype, const guint32 id);
424 
429 WS_DLL_PUBLIC conversation_t *find_conversation_strat(const packet_info *pinfo, const conversation_type ctype, const guint options);
430 
434 WS_DLL_PUBLIC conversation_t *find_conversation_pinfo(const packet_info *pinfo, const guint options);
435 
442 WS_DLL_PUBLIC conversation_t *find_conversation_pinfo_ro(const packet_info *pinfo, const guint options);
443 
454 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation(packet_info *pinfo);
455 
460 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation_by_id(packet_info *pinfo, const conversation_type ctype, const guint32 id);
461 
467 WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto, void *proto_data);
468 
474 WS_DLL_PUBLIC void *conversation_get_proto_data(const conversation_t *conv, const int proto);
475 
480 WS_DLL_PUBLIC void conversation_delete_proto_data(conversation_t *conv, const int proto);
481 
482 WS_DLL_PUBLIC void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle);
483 
484 WS_DLL_PUBLIC void conversation_set_dissector_from_frame_number(conversation_t *conversation,
485  const guint32 starting_frame_num, const dissector_handle_t handle);
486 
487 WS_DLL_PUBLIC dissector_handle_t conversation_get_dissector(conversation_t *conversation, const guint32 frame_num);
488 
500 WS_DLL_PUBLIC void conversation_set_conv_addr_port_endpoints(struct _packet_info *pinfo, address* addr1, address* addr2,
501  conversation_type ctype, guint32 port1, guint32 port2);
502 
511 WS_DLL_PUBLIC void conversation_set_elements_by_id(struct _packet_info *pinfo,
512  conversation_type ctype, guint32 id);
513 
522 WS_DLL_PUBLIC guint32 conversation_get_id_from_elements(struct _packet_info *pinfo,
523  conversation_type ctype, const guint options);
524 
535 WS_DLL_PUBLIC gboolean try_conversation_dissector(const address *addr_a, const address *addr_b, const conversation_type ctype,
536  const guint32 port_a, const guint32 port_b, tvbuff_t *tvb, packet_info *pinfo,
537  proto_tree *tree, void* data, const guint options);
538 
539 WS_DLL_PUBLIC gboolean try_conversation_dissector_by_id(const conversation_type ctype, const guint32 id, tvbuff_t *tvb,
540  packet_info *pinfo, proto_tree *tree, void* data);
541 
542 /* These routines are used to set undefined values for a conversation */
543 
549 WS_DLL_PUBLIC void conversation_set_port2(conversation_t *conv, const guint32 port);
550 
556 WS_DLL_PUBLIC void conversation_set_addr2(conversation_t *conv, const address *addr);
557 
564 WS_DLL_PUBLIC wmem_map_t *get_conversation_hashtables(void);
565 
566 /* Temporary function to handle port_type to conversation_type conversion
567  For now it's a 1-1 mapping, but the intention is to remove
568  many of the port_type instances in favor of conversation_type
569  */
570 WS_DLL_PUBLIC conversation_type conversation_pt_to_conversation_type(port_type pt);
571 
572 /* Temporary function to handle port_type to endpoint_type conversion
573  For now it's a 1-1 mapping, but the intention is to remove
574  many of the port_type instances in favor of endpoint_type
575  */
576 WS_DLL_PUBLIC endpoint_type conversation_pt_to_endpoint_type(port_type pt);
577 
578 #ifdef __cplusplus
579 }
580 #endif /* __cplusplus */
581 
582 #endif /* conversation.h */
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * conversation_new_deinterlacer(const guint32 setup_frame, const address *addr1, const address *addr2, const conversation_type ctype, const guint32 key1, const guint32 key2, const guint32 key3)
Definition: conversation.c:1100
void conversation_epan_reset(void)
Definition: conversation.c:697
WS_DLL_PUBLIC conversation_t * find_conversation_deinterlacer_pinfo(const packet_info *pinfo)
Definition: conversation.c:2020
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * find_or_create_conversation(packet_info *pinfo)
Definition: conversation.c:2373
WS_DLL_PUBLIC void conversation_set_port2(conversation_t *conv, const guint32 port)
Definition: conversation.c:1239
struct conversation conversation_t
WS_DLL_PUBLIC wmem_map_t * get_conversation_hashtables(void)
Get a hash table of conversation hash table.
Definition: conversation.c:2467
WS_DLL_PUBLIC void conversation_set_addr2(conversation_t *conv, const address *addr)
Definition: conversation.c:1283
WS_DLL_PUBLIC conversation_t * find_conversation(const guint32 frame_num, const address *addr_a, const address *addr_b, const conversation_type ctype, const guint32 port_a, const guint32 port_b, const guint options)
Definition: conversation.c:1560
WS_DLL_PUBLIC gboolean try_conversation_dissector(const address *addr_a, const address *addr_b, const conversation_type ctype, const guint32 port_a, const guint32 port_b, tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data, const guint options)
Definition: conversation.c:2168
WS_DLL_PUBLIC conversation_t * find_conversation_strat(const packet_info *pinfo, const conversation_type ctype, const guint options)
Definition: conversation.c:2249
WS_DLL_PUBLIC void * conversation_get_proto_data(const conversation_t *conv, const int proto)
Definition: conversation.c:2086
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * conversation_new_strat(packet_info *pinfo, const conversation_type ctype, const guint options)
Definition: conversation.c:1058
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * conversation_new_full(const guint32 setup_frame, conversation_element_t *elements)
Definition: conversation.c:824
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * conversation_new(const guint32 setup_frame, const address *addr1, const address *addr2, const conversation_type ctype, const guint32 port1, const guint32 port2, const guint options)
Definition: conversation.c:868
WS_DLL_PUBLIC conversation_t * find_conversation_full(const guint32 frame_num, conversation_element_t *elements)
Definition: conversation.c:1357
WS_DLL_PUBLIC void conversation_delete_proto_data(conversation_t *conv, const int proto)
Definition: conversation.c:2100
struct conversation_element conversation_element_t
WS_DLL_PUBLIC guint32 conversation_get_id_from_elements(struct _packet_info *pinfo, conversation_type ctype, const guint options)
Get the ID value from the conversation elements in the packet info.
Definition: conversation.c:2449
WS_DLL_PUBLIC conversation_t * find_conversation_pinfo(const packet_info *pinfo, const guint options)
Definition: conversation.c:2270
void conversation_init(void)
Definition: conversation.c:538
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * find_or_create_conversation_by_id(packet_info *pinfo, const conversation_type ctype, const guint32 id)
Definition: conversation.c:2401
WS_DLL_PUBLIC void conversation_set_elements_by_id(struct _packet_info *pinfo, conversation_type ctype, guint32 id)
Definition: conversation.c:2439
conversation_element_type
Definition: conversation.h:166
WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto, void *proto_data)
Definition: conversation.c:2073
WS_DLL_PUBLIC void conversation_set_conv_addr_port_endpoints(struct _packet_info *pinfo, address *addr1, address *addr2, conversation_type ctype, guint32 port1, guint32 port2)
Definition: conversation.c:2419
WS_DLL_PUBLIC conversation_t * find_conversation_pinfo_ro(const packet_info *pinfo, const guint options)
Definition: conversation.c:2325
Definition: address.h:56
Definition: packet_info.h:44
Definition: proto.h:904
Definition: wmem_map.c:44
Definition: wmem_tree-int.h:48
Definition: conversation.c:48
Definition: conversation.h:199
Definition: conversation.h:220
wmem_tree_t * dissector_tree
Definition: conversation.h:229
guint32 setup_frame
Definition: conversation.h:225
struct conversation * last
Definition: conversation.h:222
struct conversation * latest_found
Definition: conversation.h:223
guint32 last_frame
Definition: conversation.h:227
guint options
Definition: conversation.h:230
guint32 conv_index
Definition: conversation.h:224
wmem_tree_t * data_list
Definition: conversation.h:228
conversation_element_t * key_ptr
Definition: conversation.h:231
Definition: packet.c:763
Definition: tvbuff-int.h:35