conversation.h

Go to the documentation of this file.

/* conversation.h
 * Routines for building lists of packets that are part of a "conversation"
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */
 
#ifndef __CONVERSATION_H__
#define __CONVERSATION_H__
 
#include "ws_symbol_export.h"
 
#include "packet.h"         /* for conversation dissector type */
#include <epan/wmem_scopes.h>
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
#define NO_ADDR2 0x01
#define NO_PORT2 0x02
#define NO_PORT2_FORCE 0x04
#define CONVERSATION_TEMPLATE 0x08
#define NO_PORTS 0x010
 
#define NO_MASK_B 0xFFFF0000
#define NO_ADDR_B 0x00010000
#define NO_PORT_B 0x00020000
#define NO_PORT_X 0x00040000
#define NO_GREEDY 0x00100000
#define EXACT_EXCLUDED 0x00200000
 
#define USE_LAST_ENDPOINT 0x08      
/* Types of conversations Wireshark knows about. */
/* XXX: There should be a way to register conversation types used only
 * within one dissector, similar to address types, instead of changing
 * the global typedef.
 */
typedef enum {
    CONVERSATION_NONE,      /* no conversation key */
    CONVERSATION_SCTP,      /* SCTP */
    CONVERSATION_TCP,       /* TCP address/port pairs */
    CONVERSATION_UDP,       /* UDP address/port pairs */
    CONVERSATION_DCCP,      /* DCCP */
    CONVERSATION_IPX,       /* IPX sockets */
    CONVERSATION_NCP,       /* NCP connection */
    CONVERSATION_EXCHG,     /* Fibre Channel exchange */
    CONVERSATION_DDP,       /* DDP AppleTalk address/port pair */
    CONVERSATION_SBCCS,     /* FICON */
    CONVERSATION_IDP,       /* XNS IDP sockets */
    CONVERSATION_TIPC,      /* TIPC PORT */
    CONVERSATION_USB,       /* USB endpoint 0xffff means the host */
    CONVERSATION_I2C,
    CONVERSATION_IBQP,      /* Infiniband QP number */
    CONVERSATION_BLUETOOTH,
    CONVERSATION_TDMOP,
    CONVERSATION_DVBCI,
    CONVERSATION_ISO14443,
    CONVERSATION_ISDN,      /* ISDN channel number */
    CONVERSATION_H223,      /* H.223 logical channel number */
    CONVERSATION_X25,       /* X.25 logical channel number */
    CONVERSATION_IAX2,      /* IAX2 call id */
    CONVERSATION_DLCI,      /* Frame Relay DLCI */
    CONVERSATION_ISUP,      /* ISDN User Part CIC */
    CONVERSATION_BICC,      /* BICC Circuit identifier */
    CONVERSATION_GSMTAP,
    CONVERSATION_IUUP,
    CONVERSATION_DVBBBF,    /* DVB Base Band Frame ISI/PLP_ID */
    CONVERSATION_IWARP_MPA, /* iWarp MPA */
    CONVERSATION_BT_UTP,    /* BitTorrent uTP Connection ID */
    CONVERSATION_LOG,       /* Logging source */
    CONVERSATION_LTP,       /* LTP Engine ID and Session Number */
    CONVERSATION_MCTP,
    CONVERSATION_NVME_MI,       /* NVMe management interface */
    CONVERSATION_BP,        /* Bundle Protocol endpoint IDs */
    CONVERSATION_SNMP,      /* SNMP */
    CONVERSATION_QUIC,      /* QUIC */
    CONVERSATION_IDN,
    CONVERSATION_IP,        /* IP */
    CONVERSATION_IPV6,      /* IPv6 */
    CONVERSATION_ETH,           /* ETHERNET classic */
    CONVERSATION_ETH_NN,        /* ETHERNET deinterlaced Interface:N VLAN:N */
    CONVERSATION_ETH_NV,        /* ETHERNET deinterlaced Interface:N VLAN:Y */
    CONVERSATION_ETH_IN,        /* ETHERNET deinterlaced Interface:Y VLAN:N */
    CONVERSATION_ETH_IV,        /* ETHERNET deinterlaced Interface:Y VLAN:Y */
    CONVERSATION_VSPC_VMOTION,  /* VMware vSPC vMotion (Telnet) */
    CONVERSATION_OPENVPN,
    CONVERSATION_PROXY,
    CONVERSATION_GNSS,
    CONVERSATION_DNP3
} conversation_type;
 
/*
 * XXX - for now, we just #define these to be the same as the
 * corresponding CONVERSATION_ values, for backwards source
 * compatibility.
 *
 * In the long term, we should make this into a separate enum,
 * with elements corresponding to conversation types that do
 * not have known endpoints removed.
 */
/* Types of conversation endpoints Wireshark knows about. */
#define ENDPOINT_NONE       CONVERSATION_NONE
#define ENDPOINT_SCTP       CONVERSATION_SCTP
#define ENDPOINT_TCP        CONVERSATION_TCP
#define ENDPOINT_UDP        CONVERSATION_UDP
#define ENDPOINT_DCCP       CONVERSATION_DCCP
#define ENDPOINT_IPX        CONVERSATION_IPX
#define ENDPOINT_NCP        CONVERSATION_NCP
#define ENDPOINT_EXCHG      CONVERSATION_EXCHG
#define ENDPOINT_DDP        CONVERSATION_DDP
#define ENDPOINT_SBCCS      CONVERSATION_SBCCS
#define ENDPOINT_IDP        CONVERSATION_IDP
#define ENDPOINT_TIPC       CONVERSATION_TIPC
#define ENDPOINT_USB        CONVERSATION_USB
#define ENDPOINT_I2C        CONVERSATION_I2C
#define ENDPOINT_IBQP       CONVERSATION_IBQP
#define ENDPOINT_BLUETOOTH  CONVERSATION_BLUETOOTH
#define ENDPOINT_TDMOP      CONVERSATION_TDMOP
#define ENDPOINT_DVBCI      CONVERSATION_DVBCI
#define ENDPOINT_ISO14443   CONVERSATION_ISO14443
#define ENDPOINT_ISDN       CONVERSATION_ISDN
#define ENDPOINT_H223       CONVERSATION_H223
#define ENDPOINT_X25        CONVERSATION_X25
#define ENDPOINT_IAX2       CONVERSATION_IAX2
#define ENDPOINT_DLCI       CONVERSATION_DLCI
#define ENDPOINT_ISUP       CONVERSATION_ISUP
#define ENDPOINT_BICC       CONVERSATION_BICC
#define ENDPOINT_GSMTAP     CONVERSATION_GSMTAP
#define ENDPOINT_IUUP       CONVERSATION_IUUP
#define ENDPOINT_DVBBBF     CONVERSATION_DVBBBF
#define ENDPOINT_IWARP_MPA  CONVERSATION_IWARP_MPA
#define ENDPOINT_BT_UTP     CONVERSATION_BT_UTP
#define ENDPOINT_LOG        CONVERSATION_LOG
#define ENDPOINT_MCTP       CONVERSATION_MCTP
#define ENDPOINT_NVME_MI    CONVERSATION_NVME_MI
#define ENDPOINT_SNMP       CONVERSATION_SNMP
#define ENDPOINT_IP     CONVERSATION_IP
#define ENDPOINT_IPv6       CONVERSATION_IPv6
#define ENDPOINT_ETH        CONVERSATION_ETH
 
typedef conversation_type endpoint_type;
 
typedef enum {
    CE_CONVERSATION_TYPE,   /* CONVERSATION_ value */
    CE_ADDRESS,             /* address */
    CE_PORT,                /* unsigned integer representing a port */
    CE_STRING,              /* string */
    CE_UINT,                /* unsigned integer not representing a port */
    CE_UINT64,              /* 64-bit unsigned integer */
    CE_INT,                 /* signed integer */
    CE_INT64,               /* signed integer */
    CE_BLOB,                /* arbitrary binary data */
} conversation_element_type;
typedef enum {…};
 
typedef struct conversation_element {
    conversation_element_type type;
    union {
        conversation_type conversation_type_val;
        address addr_val;
        unsigned int port_val;
        const char *str_val;
        unsigned int uint_val;
        uint64_t uint64_val;
        int int_val;
        int64_t int64_val;
        struct {
            const uint8_t *val;
            size_t len;
        } blob;
    };
} conversation_element_t;
typedef struct conversation_element {…};
 
typedef struct conversation {
    struct conversation *next;  
    struct conversation *last;  
    struct conversation *latest_found; 
    uint32_t    conv_index;     
    uint32_t setup_frame;       
    /* Assume that setup_frame is also the lowest frame number for now. */
    uint32_t last_frame;        
    wmem_tree_t *data_list;     
    wmem_tree_t *dissector_tree;    
    unsigned    options;        
    conversation_element_t *key_ptr;    
} conversation_t;
typedef struct conversation {…};
 
/*
 * For some protocols, we store, in the packet_info structure, a pair
 * of address/port endpoints, for use by code that might want to
 * construct a conversation for that protocol.
 *
 * This appears to have been done in order to allow protocols to save
 * that information *without* overwriting the addresses or ports in the
 * packet_info structure, so that the other code that uses those values,
 * such as the code that fills in the address and port columns in the
 * packet summary, will pick up the values put there by protocols such
 * as IP and UDP, rather than the values put there by protocols such as
 * TDMoP, FCIP, TIPC, and DVB Dynamic Mode Adaptation. See commit
 * 66b441f3d63e21949530d672bf1406dea94ed254 and issue #11340.
 *
 * That is set by conversation_set_conv_addr_port_endpoints().
 *
 * In find_conversation_pinfo() and find_or_create_conversation(), if
 * any dissector has set this, that address/port endpoint pair is used
 * to look up or create the conversation.
 *
 * Prior to 4.0, conversations identified by a single integer value
 * (such as a circuit ID) were handled by creating a pair of address/port
 * endpoints with null addresses, the first port equal to the integer
 * value, the second port missing, and a port type being an ENDPOINT_
 * type specifying the protocol for the conversation.  Now we use an
 * array of elements, with a CE_UINT value for the integer followed
 * by a CE_CONVERSATION_TYPE value specifying the protocol for the
 * conversation.
 *
 * XXX - is there any reason why we shouldn't use an array of conversation
 * elements, with the appropriate addresses and ports, instead of this
 * structure?  It would at least simplify find_conversation_pinfo() and
 * find_or_create_conversation().
 */
struct conversation_addr_port_endpoints;
typedef struct conversation_addr_port_endpoints* conversation_addr_port_endpoints_t;
 
WS_DLL_PUBLIC const address* conversation_key_addr1(const conversation_element_t *key);
WS_DLL_PUBLIC uint32_t conversation_key_port1(const conversation_element_t *key);
WS_DLL_PUBLIC const address* conversation_key_addr2(const conversation_element_t *key);
WS_DLL_PUBLIC uint32_t conversation_key_port2(const conversation_element_t *key);
 
extern void conversation_init(void);
 
extern void conversation_epan_reset(void);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_full(const uint32_t setup_frame, conversation_element_t *elements);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new(const uint32_t setup_frame, const address *addr1, const address *addr2,
    const conversation_type ctype, const uint32_t port1, const uint32_t port2, const unsigned options);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_by_id(const uint32_t setup_frame, const conversation_type ctype, const uint32_t id);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_deinterlaced(const uint32_t setup_frame, const address *addr1, const address *addr2,
    const conversation_type ctype, const uint32_t port1, const uint32_t port2, const uint32_t anchor, const unsigned options);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_deinterlacer(const uint32_t setup_frame, const address *addr1, const address *addr2,
    const conversation_type ctype, const uint32_t key1, const uint32_t key2, const uint32_t key3);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_strat(const packet_info *pinfo, const conversation_type ctype, const unsigned options);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_strat_xtd(const packet_info *pinfo, const uint32_t setup_frame, const address *addr1, const address *addr2,
    const conversation_type ctype, const uint32_t port1, const uint32_t port2, const unsigned options);
 
WS_DLL_PUBLIC conversation_t *find_conversation_full(const uint32_t frame_num, conversation_element_t *elements);
 
WS_DLL_PUBLIC conversation_t *find_conversation(const uint32_t frame_num, const address *addr_a, const address *addr_b,
    const conversation_type ctype, const uint32_t port_a, const uint32_t port_b, const unsigned options);
 
WS_DLL_PUBLIC conversation_t *find_conversation_deinterlaced(const uint32_t frame_num, const address *addr_a, const address *addr_b,
    const conversation_type ctype, const uint32_t port_a, const uint32_t port_b, const uint32_t anchor, const unsigned options);
 
WS_DLL_PUBLIC conversation_t *find_conversation_deinterlacer(const uint32_t frame_num, const address *addr_a, const address *addr_b,
    const conversation_type ctype, const uint32_t key_a, const uint32_t key_b, const uint32_t key_c);
 
WS_DLL_PUBLIC conversation_t *find_conversation_deinterlacer_pinfo(const packet_info *pinfo);
 
WS_DLL_PUBLIC conversation_t *find_conversation_by_id(const uint32_t frame, const conversation_type ctype, const uint32_t id);
 
WS_DLL_PUBLIC conversation_t *find_conversation_strat(const packet_info *pinfo, const conversation_type ctype, const unsigned options, const bool direction);
WS_DLL_PUBLIC conversation_t *find_conversation_strat_xtd(const packet_info *pinfo, const uint32_t setup_frame, const address *addr1, const address *addr2,
    const conversation_type ctype, const uint32_t port1, const uint32_t port2, const unsigned options);
 
 
WS_DLL_PUBLIC conversation_t *find_conversation_pinfo(const packet_info *pinfo, const unsigned options);
 
WS_DLL_PUBLIC conversation_t *find_conversation_pinfo_strat(const packet_info *pinfo, const unsigned options);
 
WS_DLL_PUBLIC conversation_t *find_conversation_pinfo_ro(const packet_info *pinfo, const unsigned options);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation(const packet_info *pinfo);
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation_strat(const packet_info *pinfo);
 
WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation_by_id(packet_info *pinfo, const conversation_type ctype, const uint32_t id);
 
WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto, void *proto_data);
 
WS_DLL_PUBLIC void *conversation_get_proto_data(const conversation_t *conv, const int proto);
 
WS_DLL_PUBLIC void conversation_delete_proto_data(conversation_t *conv, const int proto);
 
WS_DLL_PUBLIC void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle);
 
WS_DLL_PUBLIC void conversation_set_dissector_from_frame_number(conversation_t *conversation,
    const uint32_t starting_frame_num, const dissector_handle_t handle);
 
WS_DLL_PUBLIC dissector_handle_t conversation_get_dissector(conversation_t *conversation, const uint32_t frame_num);
 
WS_DLL_PUBLIC void conversation_set_conv_addr_port_endpoints(struct _packet_info *pinfo, address* addr1, address* addr2,
    conversation_type ctype, uint32_t port1, uint32_t port2);
 
WS_DLL_PUBLIC void conversation_set_elements_by_id(struct _packet_info *pinfo,
    conversation_type ctype, uint32_t id);
 
WS_DLL_PUBLIC uint32_t conversation_get_id_from_elements(struct _packet_info *pinfo,
    conversation_type ctype, const unsigned options);
 
WS_DLL_PUBLIC bool try_conversation_dissector(const address *addr_a, const address *addr_b, const conversation_type ctype,
    const uint32_t port_a, const uint32_t port_b, tvbuff_t *tvb, packet_info *pinfo,
    proto_tree *tree, void* data, const unsigned options);
 
WS_DLL_PUBLIC bool try_conversation_dissector_strat(packet_info *pinfo, const conversation_type ctype,
    tvbuff_t *tvb, proto_tree *tree, void* data, const unsigned options);
 
WS_DLL_PUBLIC bool try_conversation_dissector_by_id(const conversation_type ctype, const uint32_t id, tvbuff_t *tvb,
    packet_info *pinfo, proto_tree *tree, void* data);
 
/* These routines are used to set undefined values for a conversation */
 
WS_DLL_PUBLIC void conversation_set_port2(conversation_t *conv, const uint32_t port);
 
WS_DLL_PUBLIC void conversation_set_addr2(conversation_t *conv, const address *addr);
 
WS_DLL_PUBLIC wmem_map_t *get_conversation_hashtables(void);
 
/* Temporary function to handle port_type to conversation_type conversion
   For now it's a 1-1 mapping, but the intention is to remove
   many of the port_type instances in favor of conversation_type
 */
WS_DLL_PUBLIC conversation_type conversation_pt_to_conversation_type(port_type pt);
 
/* Temporary function to handle port_type to endpoint_type conversion
   For now it's a 1-1 mapping, but the intention is to remove
   many of the port_type instances in favor of endpoint_type
 */
WS_DLL_PUBLIC endpoint_type conversation_pt_to_endpoint_type(port_type pt);
 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
#endif /* conversation.h */