epan/addr_resolv.h

   1 /* addr_resolv.h
   2  * Definitions for network object lookup
   3  *
   4  * Laurent Deniel <laurent.deniel@free.fr>
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * SPDX-License-Identifier: GPL-2.0-or-later
  11  */
  12 /* The buffers returned by these functions are all allocated with a
  13  * packet lifetime and does not have have to be freed.
  14  * However, take into account that when the packet dissection
  15  * completes, these buffers will be automatically reclaimed/freed.
  16  * If you need the buffer to remain for a longer scope than packet lifetime
  17  * you must copy the content to an wmem_file_scope() buffer.
  18  */
  19
  20 #ifndef __RESOLV_H__
  21 #define __RESOLV_H__
  22
  23 #include <epan/address.h>
  24 #include <epan/tvbuff.h>
  25 #include <epan/ipv6.h>
  26 #include <epan/to_str.h>
  27 #include <wiretap/wtap.h>
  28 #include "ws_symbol_export.h"
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif /* __cplusplus */
  33
  34 #ifndef MAXNAMELEN
  35 #define MAXNAMELEN      64      /* max name length (hostname and port name) */
  36 #endif
  37
  38 #ifndef MAXVLANNAMELEN
  39 #define MAXVLANNAMELEN          128     /* max vlan name length */
  40 #endif
  41
  42 #define BASE_ENTERPRISES     BASE_CUSTOM
  43 #define STRINGS_ENTERPRISES  CF_FUNC(enterprises_base_custom)
  44
  45 /**
  46  * @brief Flags to control name resolution.
  47  */
  48 typedef struct _e_addr_resolve {
  49   gboolean mac_name;                          /**< Whether to resolve Ethernet MAC to manufacturer names */
  50   gboolean network_name;                      /**< Whether to resolve IPv4, IPv6, and IPX addresses into host names */
  51   gboolean transport_name;                    /**< Whether to resolve TCP/UDP/DCCP/SCTP ports into service names */
  52   gboolean dns_pkt_addr_resolution;           /**< Whether to resolve addresses using captured DNS packets */
  53   gboolean use_external_net_name_resolver;    /**< Whether to system's configured DNS server to resolve names */
  54   gboolean load_hosts_file_from_profile_only; /**< Whether to only load the hosts in the current profile, not hosts files */
  55   gboolean vlan_name;                         /**< Whether to resolve VLAN IDs to names */
  56   gboolean ss7pc_name;                        /**< Whether to resolve SS7 Point Codes to names */
  57 } e_addr_resolve;
  58
  59 #define ADDR_RESOLV_MACADDR(at) \
  60     (((at)->type == AT_ETHER))
  61
  62 #define ADDR_RESOLV_NETADDR(at) \
  63     (((at)->type == AT_IPv4) || ((at)->type == AT_IPv6) || ((at)->type == AT_IPX))
  64
  65 struct hashether;
  66 typedef struct hashether hashether_t;
  67
  68 struct hashmanuf;
  69 typedef struct hashmanuf hashmanuf_t;
  70
  71 typedef struct serv_port {
  72   gchar            *udp_name;
  73   gchar            *tcp_name;
  74   gchar            *sctp_name;
  75   gchar            *dccp_name;
  76   gchar            *numeric;
  77 } serv_port_t;
  78
  79 typedef struct _resolved_name {
  80     char             name[MAXNAMELEN];
  81 } resolved_name_t;
  82
  83 /*
  84  * Flags for various IPv4/IPv6 hash table entries.
  85  */
  86 #define TRIED_RESOLVE_ADDRESS    (1U<<0)  /* XXX - what does this bit *really* mean? */
  87 #define NAME_RESOLVED            (1U<<1)  /* the name field contains a host name, not a printable address */
  88 #define RESOLVED_ADDRESS_USED    (1U<<2)  /* a get_hostname* call returned the host name */
  89
  90 #define TRIED_OR_RESOLVED_MASK   (TRIED_RESOLVE_ADDRESS | NAME_RESOLVED)
  91 #define USED_AND_RESOLVED_MASK   (NAME_RESOLVED | RESOLVED_ADDRESS_USED)
  92
  93 /*
  94  * Flag controlling what names to resolve.
  95  */
  96 WS_DLL_PUBLIC e_addr_resolve gbl_resolv_flags;
  97
  98 /* global variables */
  99
 100 extern gchar *g_ethers_path;
 101 extern gchar *g_ipxnets_path;
 102 extern gchar *g_pethers_path;
 103 extern gchar *g_pipxnets_path;
 104
 105 /* Functions in addr_resolv.c */
 106
 107 /*
 108  * udp_port_to_display() returns the port name corresponding to that UDP port,
 109  * or the port number as a string if not found.
 110  */
 111 WS_DLL_PUBLIC gchar *udp_port_to_display(wmem_allocator_t *allocator, guint port);
 112
 113 /*
 114  * tcp_port_to_display() returns the port name corresponding to that TCP port,
 115  * or the port number as a string if not found.
 116  */
 117 WS_DLL_PUBLIC gchar *tcp_port_to_display(wmem_allocator_t *allocator, guint port);
 118
 119 /*
 120  * dccp_port_to_display() returns the port name corresponding to that DCCP port,
 121  * or the port number as a string if not found.
 122  */
 123 extern gchar *dccp_port_to_display(wmem_allocator_t *allocator, guint port);
 124
 125 /*
 126  * sctp_port_to_display() returns the port name corresponding to that SCTP port,
 127  * or the port number as a string if not found.
 128  */
 129 WS_DLL_PUBLIC gchar *sctp_port_to_display(wmem_allocator_t *allocator, guint port);
 130
 131 /*
 132  * serv_name_lookup() returns the well known service name string, or numeric
 133  * representation if one doesn't exist.
 134  */
 135 WS_DLL_PUBLIC const gchar *serv_name_lookup(port_type proto, guint port);
 136
 137 /*
 138  * enterprises_lookup() returns the private enterprise code string, or 'unknown_str'
 139  * if one doesn't exist, or "<Unknown>" if that is NULL.
 140  */
 141 WS_DLL_PUBLIC const gchar *enterprises_lookup(guint32 value, const char *unknown_str);
 142
 143 /*
 144  * try_enterprises_lookup() returns the private enterprise code string, or NULL if not found.
 145  */
 146 WS_DLL_PUBLIC const gchar *try_enterprises_lookup(guint32 value);
 147
 148 /*
 149  * enterprises_base_custom() prints the "name (decimal)" string to 'buf'.
 150  * (Used with BASE_CUSTOM field display).
 151  */
 152 WS_DLL_PUBLIC void enterprises_base_custom(char *buf, guint32 value);
 153
 154 /*
 155  * try_serv_name_lookup() returns the well known service name string, or NULL if
 156  * one doesn't exist.
 157  */
 158 WS_DLL_PUBLIC const gchar *try_serv_name_lookup(port_type proto, guint port);
 159
 160 /*
 161  * port_with_resolution_to_str() prints the "<resolved> (<numerical>)" port
 162  * string.
 163  */
 164 WS_DLL_PUBLIC gchar *port_with_resolution_to_str(wmem_allocator_t *scope,
 165                                         port_type proto, guint port);
 166
 167 /*
 168  * port_with_resolution_to_str_buf() prints the "<resolved> (<numerical>)" port
 169  * string to 'buf'. Return value is the same as g_snprintf().
 170  */
 171 WS_DLL_PUBLIC int port_with_resolution_to_str_buf(gchar *buf, gulong buf_size,
 172                                         port_type proto, guint port);
 173
 174 /*
 175  * Asynchronous host name lookup initialization, processing, and cleanup
 176  */
 177
 178 /* Setup name resolution preferences */
 179 struct pref_module;
 180 extern void addr_resolve_pref_init(struct pref_module *nameres);
 181 extern void addr_resolve_pref_apply(void);
 182
 183 /*
 184  * disable_name_resolution() sets all relevant gbl_resolv_flags to FALSE.
 185  */
 186 WS_DLL_PUBLIC void disable_name_resolution(void);
 187
 188 /** If we're using c-ares process outstanding host name lookups.
 189  *  This is called from a GLIB timeout in Wireshark and before processing
 190  *  each packet in TShark.
 191  *
 192  * @return True if any new objects have been resolved since the previous
 193  * call. This can be used to trigger a display update, e.g. in Wireshark.
 194  */
 195 WS_DLL_PUBLIC gboolean host_name_lookup_process(void);
 196
 197 /* get_hostname returns the host name or "%d.%d.%d.%d" if not found */
 198 WS_DLL_PUBLIC const gchar *get_hostname(const guint addr);
 199
 200 /* get_hostname6 returns the host name, or numeric addr if not found */
 201 WS_DLL_PUBLIC const gchar *get_hostname6(const ws_in6_addr *ad);
 202
 203 /* get_ether_name returns the logical name if found in ethers files else
 204    "<vendor>_%02x:%02x:%02x" if the vendor code is known else
 205    "%02x:%02x:%02x:%02x:%02x:%02x" */
 206 WS_DLL_PUBLIC const gchar *get_ether_name(const guint8 *addr);
 207
 208 /* get_hostname_ss7pc returns the logical name if found in ss7pcs file else
 209    '\0' on the first call or the unresolved Point Code in the subsequent calls */
 210 const gchar *get_hostname_ss7pc(const guint8 ni, const guint32 pc);
 211
 212 /* fill_unresolved_ss7pc initializes the unresolved Point Code Address string in the hashtable */
 213 void fill_unresolved_ss7pc(const gchar * pc_addr, const guint8 ni, const guint32 pc);
 214
 215
 216 /* Same as get_ether_name with tvb support */
 217 WS_DLL_PUBLIC const gchar *tvb_get_ether_name(tvbuff_t *tvb, gint offset);
 218
 219 /* get_ether_name_if_known returns the logical name if found in ethers files else NULL */
 220 const gchar *get_ether_name_if_known(const guint8 *addr);
 221
 222 /*
 223  * Given a sequence of 3 octets containing an OID, get_manuf_name()
 224  * returns the vendor name, or "%02x:%02x:%02x" if not known.
 225  */
 226 extern const gchar *get_manuf_name(const guint8 *addr);
 227
 228 /*
 229  * Given a sequence of 3 octets containing an OID, get_manuf_name_if_known()
 230  * returns the vendor name, or NULL if not known.
 231  */
 232 WS_DLL_PUBLIC const gchar *get_manuf_name_if_known(const guint8 *addr);
 233
 234 /*
 235  * Given an integer containing a 24-bit OID, uint_get_manuf_name_if_known()
 236  * returns the vendor name, or NULL if not known.
 237  */
 238 extern const gchar *uint_get_manuf_name_if_known(const guint oid);
 239
 240 /*
 241  * Given a tvbuff and an offset in that tvbuff for a 3-octet OID,
 242  * tvb_get_manuf_name() returns the vendor name, or "%02x:%02x:%02x"
 243  * if not known.
 244  */
 245 WS_DLL_PUBLIC const gchar *tvb_get_manuf_name(tvbuff_t *tvb, gint offset);
 246
 247 /*
 248  * Given a tvbuff and an offset in that tvbuff for a 3-octet OID,
 249  * tvb_get_manuf_name_if_known() returns the vendor name, or NULL
 250  * if not known.
 251  */
 252 WS_DLL_PUBLIC const gchar *tvb_get_manuf_name_if_known(tvbuff_t *tvb, gint offset);
 253
 254 /* eui64_to_display returns "<vendor>_%02x:%02x:%02x:%02x:%02x:%02x" if the vendor code is known
 255    "%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x" */
 256 extern gchar *eui64_to_display(wmem_allocator_t *allocator, const guint64 addr);
 257
 258 /* get_ipxnet_name returns the logical name if found in an ipxnets file,
 259  * or a string formatted with "%X" if not */
 260 extern gchar *get_ipxnet_name(wmem_allocator_t *allocator, const guint32 addr);
 261
 262 /* get_vlan_name returns the logical name if found in a vlans file,
 263  * or the VLAN ID itself as a string if not found*/
 264 extern gchar *get_vlan_name(wmem_allocator_t *allocator, const guint16 id);
 265
 266 WS_DLL_PUBLIC guint get_hash_ether_status(hashether_t* ether);
 267 WS_DLL_PUBLIC char* get_hash_ether_hexaddr(hashether_t* ether);
 268 WS_DLL_PUBLIC char* get_hash_ether_resolved_name(hashether_t* ether);
 269
 270 WS_DLL_PUBLIC char* get_hash_manuf_resolved_name(hashmanuf_t* manuf);
 271
 272
 273 /* adds a hostname/IPv4 in the hash table */
 274 WS_DLL_PUBLIC void add_ipv4_name(const guint addr, const gchar *name);
 275
 276 /* adds a hostname/IPv6 in the hash table */
 277 WS_DLL_PUBLIC void add_ipv6_name(const ws_in6_addr *addr, const gchar *name);
 278
 279 /** Add an additional "hosts" file for IPv4 and IPv6 name resolution.
 280  *
 281  * The file can be added before host_name_lookup_init() is called and
 282  * will be re-read each time host_name_lookup_init() is called.
 283  *
 284  * @param hosts_file Absolute path to the hosts file.
 285  *
 286  * @return TRUE if the hosts file can be read.
 287  */
 288 WS_DLL_PUBLIC gboolean add_hosts_file (const char *hosts_file);
 289
 290 /* adds a hostname in the hash table */
 291 WS_DLL_PUBLIC gboolean add_ip_name_from_string (const char *addr, const char *name);
 292
 293 /* Get the user defined name, for a given address */
 294 WS_DLL_PUBLIC resolved_name_t* get_edited_resolved_name(const char* addr);
 295
 296
 297 /** Get lists of host name to address mappings we know about.
 298  *
 299  * The struct contains two g_lists one with hashipv4_t entries and one with hashipv6_t entries.
 300  *
 301  * @return a struct with lists of known addresses(IPv4 and IPv6). May be NULL.
 302  */
 303 WS_DLL_PUBLIC addrinfo_lists_t *get_addrinfo_list(void);
 304
 305 /* add ethernet address / name corresponding to IP address  */
 306 extern void add_ether_byip(const guint ip, const guint8 *eth);
 307
 308 /** Translates a string representing a hostname or dotted-decimal IPv4 address
 309  *  into a numeric IPv4 address value in network byte order. If compiled with
 310  *  c-ares, the request will wait a maximum of 250ms for the request to finish.
 311  *  Otherwise the wait time will be system-dependent, ususally much longer.
 312  *  Immediately returns FALSE for hostnames if network name resolution is
 313  *  disabled.
 314  *
 315  * @param[in] host The hostname.
 316  * @param[out] addrp The numeric IPv4 address in network byte order.
 317  * @return TRUE on success, FALSE on failure, timeout.
 318  */
 319 WS_DLL_PUBLIC
 320 gboolean get_host_ipaddr(const char *host, guint32 *addrp);
 321
 322 /** Translates a string representing a hostname or colon-hex IPv6 address
 323  *  into a numeric IPv6 address value in network byte order. If compiled with
 324  *  c-ares, the request will wait a maximum of 250ms for the request to finish.
 325  *  Otherwise the wait time will be system-dependent, usually much longer.
 326  *  Immediately returns FALSE for hostnames if network name resolution is
 327  *  disabled.
 328  *
 329  * @param[in] host The hostname.
 330  * @param[out] addrp The numeric IPv6 address in network byte order.
 331  * @return TRUE on success, FALSE on failure or timeout.
 332  */
 333 WS_DLL_PUBLIC
 334 gboolean get_host_ipaddr6(const char *host, ws_in6_addr *addrp);
 335
 336 WS_DLL_PUBLIC
 337 wmem_map_t *get_manuf_hashtable(void);
 338
 339 WS_DLL_PUBLIC
 340 wmem_map_t *get_wka_hashtable(void);
 341
 342 WS_DLL_PUBLIC
 343 wmem_map_t *get_eth_hashtable(void);
 344
 345 WS_DLL_PUBLIC
 346 wmem_map_t *get_serv_port_hashtable(void);
 347
 348 WS_DLL_PUBLIC
 349 wmem_map_t *get_ipxnet_hash_table(void);
 350
 351 WS_DLL_PUBLIC
 352 wmem_map_t *get_vlan_hash_table(void);
 353
 354 WS_DLL_PUBLIC
 355 wmem_map_t *get_ipv4_hash_table(void);
 356
 357 WS_DLL_PUBLIC
 358 wmem_map_t *get_ipv6_hash_table(void);
 359
 360 /*
 361  * XXX - if we ever have per-session host name etc. information, we
 362  * should probably have the "resolve synchronously or asynchronously"
 363  * flag be per-session, set with an epan API.
 364  */
 365 WS_DLL_PUBLIC
 366 void set_resolution_synchrony(gboolean synchronous);
 367
 368 /*
 369  * private functions (should only be called by epan directly)
 370  */
 371
 372 WS_DLL_LOCAL
 373 void name_resolver_init(void);
 374
 375 /* Reinitialize hostname resolution subsystem */
 376 WS_DLL_LOCAL
 377 void host_name_lookup_reset(void);
 378
 379 WS_DLL_LOCAL
 380 void addr_resolv_init(void);
 381
 382 WS_DLL_LOCAL
 383 void addr_resolv_cleanup(void);
 384
 385 WS_DLL_PUBLIC
 386 gboolean str_to_ip(const char *str, void *dst);
 387
 388 WS_DLL_PUBLIC
 389 gboolean str_to_ip6(const char *str, void *dst);
 390
 391 WS_DLL_LOCAL
 392 gboolean str_to_eth(const char *str, char *eth_bytes);
 393
 394 WS_DLL_LOCAL
 395 guint ipv6_oat_hash(gconstpointer key);
 396
 397 WS_DLL_LOCAL
 398 gboolean ipv6_equal(gconstpointer v1, gconstpointer v2);
 399
 400 #ifdef __cplusplus
 401 }
 402 #endif /* __cplusplus */
 403
 404 #endif /* __RESOLV_H__ */