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
 */
#pragma once
#include "ws_symbol_export.h"
 
#include <epan/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      

typedef enum {
    CONVERSATION_NONE,           
    CONVERSATION_SCTP,           
    CONVERSATION_TCP,            
    CONVERSATION_UDP,            
    CONVERSATION_DCCP,           
    CONVERSATION_IPX,            
    CONVERSATION_NCP,            
    CONVERSATION_EXCHG,          
    CONVERSATION_DDP,            
    CONVERSATION_SBCCS,          
    CONVERSATION_IDP,            
    CONVERSATION_TIPC,           
    CONVERSATION_USB,            
    CONVERSATION_I2C,            
    CONVERSATION_IBQP,           
    CONVERSATION_BLUETOOTH,      
    CONVERSATION_TDMOP,          
    CONVERSATION_DVBCI,          
    CONVERSATION_ISO14443,       
    CONVERSATION_ISDN,           
    CONVERSATION_H223,           
    CONVERSATION_X25,            
    CONVERSATION_IAX2,           
    CONVERSATION_DLCI,           
    CONVERSATION_ISUP,           
    CONVERSATION_BICC,           
    CONVERSATION_GSMTAP,         
    CONVERSATION_IUUP,           
    CONVERSATION_DVBBBF,         
    CONVERSATION_IWARP_MPA,      
    CONVERSATION_BT_UTP,         
    CONVERSATION_LOG,            
    CONVERSATION_LTP,            
    CONVERSATION_MCTP,           
    CONVERSATION_NVME_MI,        
    CONVERSATION_BP,             
    CONVERSATION_SNMP,           
    CONVERSATION_QUIC,           
    CONVERSATION_IDN,            
    CONVERSATION_IP,             
    CONVERSATION_IPV6,           
    CONVERSATION_ETH,            
    CONVERSATION_ETH_NN,         
    CONVERSATION_ETH_NV,         
    CONVERSATION_ETH_IN,         
    CONVERSATION_ETH_IV,         
    CONVERSATION_VSPC_VMOTION,   
    CONVERSATION_OPENVPN,        
    CONVERSATION_PROXY,          
    CONVERSATION_GNSS,           
    CONVERSATION_DNP3,           
    CONVERSATION_ILNP,           
    CONVERSATION_SYNCHROPHASOR,  
    CONVERSATION_UDX,            
} 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
#define ENDPOINT_ILNP       CONVERSATION_ILNP
#define ENDPOINT_UDX        CONVERSATION_UDX
 
typedef conversation_type endpoint_type;

typedef enum {
    CE_CONVERSATION_TYPE,   
    CE_ADDRESS,             
    CE_PORT,                
    CE_STRING,              
    CE_UINT,                
    CE_UINT64,              
    CE_INT,                 
    CE_INT64,               
    CE_BLOB,                
} conversation_element_type;

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 {
    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;
 
/*
 * 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_err_pkts(const uint32_t setup_frame, const conversation_type ctype, const uint32_t id, const uint32_t rid);

WS_DLL_PUBLIC bool is_deinterlacing_supported(const packet_info *pinfo);

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_err_pkts(const uint32_t frame, const conversation_type ctype, const uint32_t id, const uint32_t rid);

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, const bool direction);

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);

WS_DLL_PUBLIC endpoint_type conversation_pt_to_endpoint_type(port_type pt);
 
#ifdef __cplusplus
}
#endif /* __cplusplus */