epan/addr_resolv.h

   1 /** @file
   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 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 <wsutil/inet_cidr.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 (most names: DNS labels, services, eth) */
  36 #endif
  37
  38 #ifndef MAXVLANNAMELEN
  39 #define MAXVLANNAMELEN          128     /* max vlan name length */
  40 #endif
  41
  42 #ifndef MAXDNSNAMELEN
  43 #define MAXDNSNAMELEN   256     /* max total length of a domain name in the DNS */
  44 #endif
  45
  46 #define BASE_ENTERPRISES     BASE_CUSTOM
  47 #define STRINGS_ENTERPRISES  CF_FUNC(enterprises_base_custom)
  48
  49 /**
  50  * @brief Flags to control name resolution.
  51  */
  52 typedef struct _e_addr_resolve {
  53   bool mac_name;                          /**< Whether to resolve Ethernet MAC to manufacturer names */
  54   bool network_name;                      /**< Whether to resolve IPv4, IPv6, and IPX addresses into host names */
  55   bool transport_name;                    /**< Whether to resolve TCP/UDP/DCCP/SCTP ports into service names */
  56   bool dns_pkt_addr_resolution;           /**< Whether to resolve addresses using captured DNS packets */
  57   bool handshake_sni_addr_resolution;     /**< Whether to resolve addresses using SNI information found in captured handshake packets */
  58   bool use_external_net_name_resolver;    /**< Whether to system's configured DNS server to resolve names */
  59   bool vlan_name;                         /**< Whether to resolve VLAN IDs to names */
  60   bool ss7pc_name;                        /**< Whether to resolve SS7 Point Codes to names */
  61   bool maxmind_geoip;                     /**< Whether to lookup geolocation information with mmdbresolve */
  62 } e_addr_resolve;
  63
  64 #define ADDR_RESOLV_MACADDR(at) \
  65     (((at)->type == AT_ETHER))
  66
  67 #define ADDR_RESOLV_NETADDR(at) \
  68     (((at)->type == AT_IPv4) || ((at)->type == AT_IPv6) || ((at)->type == AT_IPX))
  69
  70 struct hashether;
  71 typedef struct hashether hashether_t;
  72
  73 struct hashwka;
  74 typedef struct hashwka hashwka_t;
  75
  76 struct hashmanuf;
  77 typedef struct hashmanuf hashmanuf_t;
  78
  79 typedef struct serv_port {
  80   const char       *udp_name;
  81   const char       *tcp_name;
  82   const char       *sctp_name;
  83   const char       *dccp_name;
  84   const char       *numeric;
  85 } serv_port_t;
  86
  87 /* Used for manually edited DNS resolved names */
  88 typedef struct _resolved_name {
  89     char             name[MAXDNSNAMELEN];
  90 } resolved_name_t;
  91
  92 /*
  93  * Flags for various resolved name hash table entries.
  94  */
  95 #define TRIED_RESOLVE_ADDRESS    (1U<<0)  /* name resolution is being/has been tried */
  96 #define NAME_RESOLVED            (1U<<1)  /* the name field contains a host name, not a printable address */
  97 #define RESOLVED_ADDRESS_USED    (1U<<2)  /* a get_hostname* call returned the host name */
  98 #define STATIC_HOSTNAME          (1U<<3)  /* do not update entries from hosts file with DNS responses */
  99 #define NAME_RESOLVED_PREFIX     (1U<<4)  /* name was generated from a prefix (e.g., OUI) instead of the entire address */
 100
 101 #define TRIED_OR_RESOLVED_MASK   (TRIED_RESOLVE_ADDRESS | NAME_RESOLVED)
 102 #define USED_AND_RESOLVED_MASK   (NAME_RESOLVED | RESOLVED_ADDRESS_USED)
 103
 104 /*
 105  * Flag controlling what names to resolve.
 106  */
 107 WS_DLL_PUBLIC e_addr_resolve gbl_resolv_flags;
 108
 109 /* global variables */
 110
 111 extern char *g_ethers_path;
 112 extern char *g_ipxnets_path;
 113 extern char *g_pethers_path;
 114 extern char *g_pipxnets_path;
 115
 116 /* Functions in addr_resolv.c */
 117
 118 /*
 119  * returns an ipv4 object built from its address
 120  */
 121 WS_DLL_PUBLIC hashipv4_t * new_ipv4(const unsigned addr);
 122
 123 /*
 124  * returns a 'dummy ip4' object built from an address
 125  */
 126 WS_DLL_PUBLIC bool fill_dummy_ip4(const unsigned addr, hashipv4_t* volatile tp);
 127
 128 /*
 129  * udp_port_to_display() returns the port name corresponding to that UDP port,
 130  * or the port number as a string if not found.
 131  */
 132 WS_DLL_PUBLIC char *udp_port_to_display(wmem_allocator_t *allocator, unsigned port);
 133
 134 /*
 135  * tcp_port_to_display() returns the port name corresponding to that TCP port,
 136  * or the port number as a string if not found.
 137  */
 138 WS_DLL_PUBLIC char *tcp_port_to_display(wmem_allocator_t *allocator, unsigned port);
 139
 140 /*
 141  * dccp_port_to_display() returns the port name corresponding to that DCCP port,
 142  * or the port number as a string if not found.
 143  */
 144 extern char *dccp_port_to_display(wmem_allocator_t *allocator, unsigned port);
 145
 146 /*
 147  * sctp_port_to_display() returns the port name corresponding to that SCTP port,
 148  * or the port number as a string if not found.
 149  */
 150 WS_DLL_PUBLIC char *sctp_port_to_display(wmem_allocator_t *allocator, unsigned port);
 151
 152 /*
 153  * serv_name_lookup() returns the well known service name string, or numeric
 154  * representation if one doesn't exist.
 155  */
 156 WS_DLL_PUBLIC const char *serv_name_lookup(port_type proto, unsigned port);
 157
 158 /*
 159  * enterprises_lookup() returns the private enterprise code string, or 'unknown_str'
 160  * if one doesn't exist, or "<Unknown>" if that is NULL.
 161  */
 162 WS_DLL_PUBLIC const char *enterprises_lookup(uint32_t value, const char *unknown_str);
 163
 164 /*
 165  * try_enterprises_lookup() returns the private enterprise code string, or NULL if not found.
 166  */
 167 WS_DLL_PUBLIC const char *try_enterprises_lookup(uint32_t value);
 168
 169 /*
 170  * enterprises_base_custom() prints the "name (decimal)" string to 'buf'.
 171  * (Used with BASE_CUSTOM field display).
 172  */
 173 WS_DLL_PUBLIC void enterprises_base_custom(char *buf, uint32_t value);
 174
 175 /*
 176  * try_serv_name_lookup() returns the well known service name string, or NULL if
 177  * one doesn't exist.
 178  */
 179 WS_DLL_PUBLIC const char *try_serv_name_lookup(port_type proto, unsigned port);
 180
 181 /*
 182  * port_with_resolution_to_str() prints the "<resolved> (<numerical>)" port
 183  * string.
 184  */
 185 WS_DLL_PUBLIC char *port_with_resolution_to_str(wmem_allocator_t *scope,
 186                                         port_type proto, unsigned port);
 187
 188 /*
 189  * port_with_resolution_to_str_buf() prints the "<resolved> (<numerical>)" port
 190  * string to 'buf'. Return value is the same as snprintf().
 191  */
 192 WS_DLL_PUBLIC int port_with_resolution_to_str_buf(char *buf, unsigned long buf_size,
 193                                         port_type proto, unsigned port);
 194
 195 /*
 196  * Asynchronous host name lookup initialization, processing, and cleanup
 197  */
 198
 199 /* Setup name resolution preferences */
 200 struct pref_module;
 201 extern void addr_resolve_pref_init(struct pref_module *nameres);
 202 extern void addr_resolve_pref_apply(void);
 203
 204 /*
 205  * disable_name_resolution() sets all relevant gbl_resolv_flags to false.
 206  */
 207 WS_DLL_PUBLIC void disable_name_resolution(void);
 208
 209 /** If we're using c-ares process outstanding host name lookups.
 210  *  This is called from a GLIB timeout in Wireshark and before processing
 211  *  each packet in the first pass of two-pass TShark.
 212  *
 213  * @return True if any new objects have been resolved since the previous
 214  * call. This can be used to trigger a display update, e.g. in Wireshark.
 215  */
 216 WS_DLL_PUBLIC bool host_name_lookup_process(void);
 217
 218 /* get_hostname returns the host name or "%d.%d.%d.%d" if not found.
 219  * The string does not have to be freed; it will be freed when the
 220  * address hashtables are emptied (e.g., when preferences change or
 221  * redissection.) However, this increases persistent memory usage
 222  * even when host name lookups are off.
 223  *
 224  * This might get deprecated in the future for get_hostname_wmem.
 225  */
 226 WS_DLL_PUBLIC const char *get_hostname(const unsigned addr);
 227
 228 /* get_hostname_wmem returns the host name or "%d.%d.%d.%d" if not found
 229  * The returned string is allocated according to the wmem scope allocator. */
 230 WS_DLL_PUBLIC char *get_hostname_wmem(wmem_allocator_t *allocator, const unsigned addr);
 231
 232 /* get_hostname6 returns the host name, or numeric addr if not found.
 233  * The string does not have to be freed; it will be freed when the
 234  * address hashtables are emptied (e.g., when preferences change or
 235  * upon redissection.) However, this increases persistent memory usage
 236  * even when host name lookups are off.
 237  *
 238  * This might get deprecated in the future for get_hostname6_wmem.
 239  */
 240 WS_DLL_PUBLIC const char *get_hostname6(const ws_in6_addr *ad);
 241
 242 /* get_hostname6 returns the host name, or numeric addr if not found.
 243  * The returned string is allocated according to the wmem scope allocator. */
 244 WS_DLL_PUBLIC char *get_hostname6_wmem(wmem_allocator_t *allocator, const ws_in6_addr *ad);
 245
 246 /* get_ether_name returns the logical name if found in ethers files else
 247    "<vendor>_%02x:%02x:%02x" if the vendor code is known else
 248    "%02x:%02x:%02x:%02x:%02x:%02x" */
 249 WS_DLL_PUBLIC const char *get_ether_name(const uint8_t *addr);
 250
 251 /* get_hostname_ss7pc returns the logical name if found in ss7pcs file else
 252    '\0' on the first call or the unresolved Point Code in the subsequent calls */
 253 const char *get_hostname_ss7pc(const uint8_t ni, const uint32_t pc);
 254
 255 /* fill_unresolved_ss7pc initializes the unresolved Point Code Address string in the hashtable */
 256 void fill_unresolved_ss7pc(const char * pc_addr, const uint8_t ni, const uint32_t pc);
 257
 258
 259 /* Same as get_ether_name with tvb support */
 260 WS_DLL_PUBLIC const char *tvb_get_ether_name(tvbuff_t *tvb, int offset);
 261
 262 /* get_ether_name_if_known returns the logical name if an exact match is
 263  * found (in ethers files or from ARP) else NULL.
 264  * @note: It returns NULL for addresses if only a prefix can be resolved
 265  * into a manufacturer name.
 266  */
 267 const char *get_ether_name_if_known(const uint8_t *addr);
 268
 269 /*
 270  * Given a sequence of 3 octets containing an OID, get_manuf_name()
 271  * returns an abbreviated form of the vendor name, or "%02x:%02x:%02x"
 272  * if not known. (The short form of the name is roughly similar in length
 273  * to the hexstring, so that they may be used in similar places.)
 274  * @note: This only looks up entries in the 24-bit OUI table (and the
 275  * CID table), not the MA-M and MA-S tables. The hex byte string is
 276  * returned for sequences registered to the IEEE Registration Authority
 277  * for the purposes of being subdivided into MA-M and MA-S.
 278  */
 279 extern const char *get_manuf_name(const uint8_t *addr, size_t size);
 280
 281 /*
 282  * Given a sequence of 3 or more octets containing an OUI,
 283  * get_manuf_name_if_known() returns the vendor name, or NULL if not known.
 284  * @note Unlike get_manuf_name() above, this returns the full vendor name.
 285  * @note If size is 6 or larger, vendor names will be looked up in the MA-M
 286  * and MA-S tables as well (but note that the length of the sequence is
 287  * not returned.) If size is less than 6, only the 24 bit tables are searched,
 288  * and NULL is returned for sequences registered to the IEEE Registration
 289  * Authority for purposes of being subdivided into MA-M and MA-S.
 290  */
 291 WS_DLL_PUBLIC const char *get_manuf_name_if_known(const uint8_t *addr, size_t size);
 292
 293 /*
 294  * Given an integer containing a 24-bit OUI (or CID),
 295  * uint_get_manuf_name_if_known() returns the vendor name, or NULL if not known.
 296  * @note NULL is returned for sequences registered to the IEEE Registration
 297  * Authority for purposes of being subdivided into MA-M and MA-S.
 298  */
 299 extern const char *uint_get_manuf_name_if_known(const uint32_t oid);
 300
 301 /*
 302  * Given a tvbuff and an offset in that tvbuff for a 3-octet OID,
 303  * tvb_get_manuf_name() returns an abbreviated vendor name, or "%02x:%02x:%02x"
 304  * if not known.
 305  * @note: This only looks up entries in the 24-bit OUI table (and the
 306  * CID table), not the MA-M and MA-S tables. The hex byte string is
 307  * returned for sequences registered to the IEEE Registration Authority
 308  * for the purposes of being subdivided into MA-M and MA-S.
 309  */
 310 WS_DLL_PUBLIC const char *tvb_get_manuf_name(tvbuff_t *tvb, int offset);
 311
 312 /*
 313  * Given a tvbuff and an offset in that tvbuff for a 3-octet OID,
 314  * tvb_get_manuf_name_if_known() returns the full vendor name, or NULL
 315  * if not known.
 316  * @note NULL is returned for sequences registered to the IEEE Registration
 317  * Authority for purposes of being subdivided into MA-M and MA-S.
 318  */
 319 WS_DLL_PUBLIC const char *tvb_get_manuf_name_if_known(tvbuff_t *tvb, int offset);
 320
 321 /* eui64_to_display returns "<vendor>_%02x:%02x:%02x:%02x:%02x:%02x" if the
 322  * vendor code is known (or as appropriate for MA-M and MA-S), and if not,
 323  * "%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x:%02x"
 324 */
 325 extern char *eui64_to_display(wmem_allocator_t *allocator, const uint64_t addr);
 326
 327 /* get_ipxnet_name returns the logical name if found in an ipxnets file,
 328  * or a string formatted with "%X" if not */
 329 extern char *get_ipxnet_name(wmem_allocator_t *allocator, const uint32_t addr);
 330
 331 /* get_vlan_name returns the logical name if found in a vlans file,
 332  * or the VLAN ID itself as a string if not found*/
 333 extern char *get_vlan_name(wmem_allocator_t *allocator, const uint16_t id);
 334
 335 WS_DLL_PUBLIC unsigned get_hash_ether_status(hashether_t* ether);
 336 WS_DLL_PUBLIC bool get_hash_ether_used(hashether_t* ether);
 337 WS_DLL_PUBLIC char* get_hash_ether_hexaddr(hashether_t* ether);
 338 WS_DLL_PUBLIC char* get_hash_ether_resolved_name(hashether_t* ether);
 339
 340 WS_DLL_PUBLIC bool get_hash_manuf_used(hashmanuf_t* manuf);
 341 WS_DLL_PUBLIC char* get_hash_manuf_resolved_name(hashmanuf_t* manuf);
 342
 343 WS_DLL_PUBLIC bool get_hash_wka_used(hashwka_t* wka);
 344 WS_DLL_PUBLIC char* get_hash_wka_resolved_name(hashwka_t* wka);
 345
 346 /* adds a hostname/IPv4 in the hash table */
 347 WS_DLL_PUBLIC void add_ipv4_name(const unsigned addr, const char *name, const bool static_entry);
 348
 349 /* adds a hostname/IPv6 in the hash table */
 350 WS_DLL_PUBLIC void add_ipv6_name(const ws_in6_addr *addr, const char *name, const bool static_entry);
 351
 352 /** Add an additional "hosts" file for IPv4 and IPv6 name resolution.
 353  *
 354  * The file can be added before host_name_lookup_init() is called and
 355  * will be re-read each time host_name_lookup_init() is called.
 356  *
 357  * @param hosts_file Absolute path to the hosts file.
 358  *
 359  * @return true if the hosts file can be read.
 360  */
 361 WS_DLL_PUBLIC bool add_hosts_file (const char *hosts_file);
 362
 363 /* adds a hostname in the hash table */
 364 WS_DLL_PUBLIC bool add_ip_name_from_string (const char *addr, const char *name);
 365
 366 /* Get the user defined name, for a given address */
 367 WS_DLL_PUBLIC resolved_name_t* get_edited_resolved_name(const char* addr);
 368
 369
 370 /** Get lists of host name to address mappings we know about.
 371  *
 372  * The struct contains two g_lists one with hashipv4_t entries and one with hashipv6_t entries.
 373  *
 374  * @return a struct with lists of known addresses(IPv4 and IPv6). May be NULL.
 375  */
 376 WS_DLL_PUBLIC addrinfo_lists_t *get_addrinfo_list(void);
 377
 378 /* add ethernet address / name corresponding to IP address  */
 379 extern void add_ether_byip(const unsigned ip, const uint8_t *eth);
 380
 381 /** Translates a string representing a hostname or dotted-decimal IPv4 address
 382  *  into a numeric IPv4 address value in network byte order. If compiled with
 383  *  c-ares, the request will wait a maximum of 250ms for the request to finish.
 384  *  Otherwise the wait time will be system-dependent, usually much longer.
 385  *  Immediately returns false for hostnames if network name resolution is
 386  *  disabled.
 387  *
 388  * @param[in] host The hostname.
 389  * @param[out] addrp The numeric IPv4 address in network byte order.
 390  * @return true on success, false on failure, timeout.
 391  */
 392 WS_DLL_PUBLIC
 393 bool get_host_ipaddr(const char *host, uint32_t *addrp);
 394
 395 /** Translates a string representing a hostname or colon-hex IPv6 address
 396  *  into a numeric IPv6 address value in network byte order. If compiled with
 397  *  c-ares, the request will wait a maximum of 250ms for the request to finish.
 398  *  Otherwise the wait time will be system-dependent, usually much longer.
 399  *  Immediately returns false for hostnames if network name resolution is
 400  *  disabled.
 401  *
 402  * @param[in] host The hostname.
 403  * @param[out] addrp The numeric IPv6 address in network byte order.
 404  * @return true on success, false on failure or timeout.
 405  */
 406 WS_DLL_PUBLIC
 407 bool get_host_ipaddr6(const char *host, ws_in6_addr *addrp);
 408
 409 WS_DLL_PUBLIC
 410 wmem_map_t *get_manuf_hashtable(void);
 411
 412 WS_DLL_PUBLIC
 413 wmem_map_t *get_wka_hashtable(void);
 414
 415 WS_DLL_PUBLIC
 416 wmem_map_t *get_eth_hashtable(void);
 417
 418 WS_DLL_PUBLIC
 419 wmem_map_t *get_serv_port_hashtable(void);
 420
 421 WS_DLL_PUBLIC
 422 wmem_map_t *get_ipxnet_hash_table(void);
 423
 424 WS_DLL_PUBLIC
 425 wmem_map_t *get_vlan_hash_table(void);
 426
 427 WS_DLL_PUBLIC
 428 wmem_map_t *get_ipv4_hash_table(void);
 429
 430 WS_DLL_PUBLIC
 431 wmem_map_t *get_ipv6_hash_table(void);
 432
 433 /*
 434  * XXX - if we ever have per-session host name etc. information, we
 435  * should probably have the "resolve synchronously or asynchronously"
 436  * flag be per-session, set with an epan API.
 437  */
 438 WS_DLL_PUBLIC
 439 void set_resolution_synchrony(bool synchronous);
 440
 441 /*
 442  * private functions (should only be called by epan directly)
 443  */
 444
 445 WS_DLL_LOCAL
 446 void name_resolver_init(void);
 447
 448 /* Reinitialize hostname resolution subsystem */
 449 WS_DLL_LOCAL
 450 void host_name_lookup_reset(void);
 451
 452 WS_DLL_LOCAL
 453 void addr_resolv_init(void);
 454
 455 WS_DLL_LOCAL
 456 void addr_resolv_cleanup(void);
 457
 458 WS_DLL_PUBLIC
 459 bool str_to_ip(const char *str, void *dst);
 460
 461 WS_DLL_PUBLIC
 462 bool str_to_ip6(const char *str, void *dst);
 463
 464 WS_DLL_LOCAL
 465 bool str_to_eth(const char *str, char *eth_bytes);
 466
 467 WS_DLL_LOCAL
 468 unsigned ipv6_oat_hash(const void *key);
 469
 470 WS_DLL_LOCAL
 471 gboolean ipv6_equal(const void *v1, const void *v2);
 472
 473 #ifdef __cplusplus
 474 }
 475 #endif /* __cplusplus */
 476
 477 #endif /* __RESOLV_H__ */