epan/address.h

   1 /** @file
   2  * Definitions for structures storing addresses, and for the type of
   3  * variables holding port-type values
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __ADDRESS_H__
  13 #define __ADDRESS_H__
  14
  15 #include <string.h>     /* for memcmp */
  16
  17 #include "tvbuff.h"
  18 #include <epan/wmem_scopes.h>
  19 #include <wsutil/ws_assert.h>
  20 #include <wsutil/inet_cidr.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif /* __cplusplus */
  25
  26 /* Types of "global" addresses Wireshark knows about. */
  27 /* Address types can be added here if there are many dissectors that use them or just
  28  * within a specific dissector.
  29  * If an address type is added here, it must be "registered" within address_types.c
  30  * For dissector address types, just use the address_type_dissector_register function
  31  * from address_types.h
  32  *
  33  * AT_NUMERIC - a numeric address type can consist of a uint8_t, uint16_t, uint32_t or uint64_t
  34  * value. If no correct length is provided, to avoid data bleed, a uint8_t is
  35  * assumed. Only representation (aka conversion of value to string) is implemented for this type.
  36  */
  37 typedef enum {
  38     AT_NONE,               /* no link-layer address */
  39     AT_ETHER,              /* MAC (Ethernet, 802.x, FDDI) address */
  40     AT_IPv4,               /* IPv4 */
  41     AT_IPv6,               /* IPv6 */
  42     AT_IPX,                /* IPX */
  43     AT_FC,                 /* Fibre Channel */
  44     AT_FCWWN,              /* Fibre Channel WWN */
  45     AT_STRINGZ,            /* null-terminated string */
  46     AT_EUI64,              /* IEEE EUI-64 */
  47     AT_IB,                 /* Infiniband GID/LID */
  48     AT_AX25,               /* AX.25 */
  49     AT_VINES,              /* Banyan Vines address */
  50     AT_NUMERIC,            /* Numeric address type. */
  51     AT_MCTP,               /* MCTP */
  52
  53     AT_END_OF_LIST         /* Must be last in list */
  54 } address_type;
  55
  56 typedef struct _address {
  57     int           type;         /* type of address */
  58     int           len;          /* length of address, in bytes */
  59     const void   *data;         /* pointer to address data */
  60
  61     /* private */
  62     void         *priv;
  63 } address;
  64
  65 #define ADDRESS_INIT(type, len, data) {type, len, data, NULL}
  66 #define ADDRESS_INIT_NONE ADDRESS_INIT(AT_NONE, 0, NULL)
  67
  68 static inline void
  69 clear_address(address *addr)
  70 {
  71     addr->type = AT_NONE;
  72     addr->len  = 0;
  73     addr->data = NULL;
  74     addr->priv = NULL;
  75 }
  76
  77 /** Initialize an address with the given values.
  78  *
  79  * @param addr [in,out] The address to initialize.
  80  * @param addr_type [in] Address type.
  81  * @param addr_len [in] The length in bytes of the address data. For example, 4 for
  82  *                     AT_IPv4 or sizeof(ws_in6_addr) for AT_IPv6.
  83  * @param addr_data [in] Pointer to the address data.
  84  */
  85 static inline void
  86 set_address(address *addr, int addr_type, int addr_len, const void *addr_data) {
  87     if (addr_len == 0) {
  88         /* Zero length must mean no data */
  89         ws_assert(addr_data == NULL);
  90     } else {
  91         /* Must not be AT_NONE - AT_NONE must have no data */
  92         ws_assert(addr_type != AT_NONE);
  93         /* Make sure we *do* have data */
  94         ws_assert(addr_data != NULL);
  95     }
  96     addr->type = addr_type;
  97     addr->len  = addr_len;
  98     addr->data = addr_data;
  99     addr->priv = NULL;
 100 }
 101
 102 static inline void
 103 set_address_ipv4(address *addr, const ipv4_addr_and_mask *ipv4) {
 104     addr->type = AT_IPv4;
 105     addr->len  = 4;
 106     uint32_t val = g_htonl(ipv4->addr);
 107     addr->priv = g_memdup2(&val, sizeof(val));
 108     addr->data = addr->priv;
 109 }
 110
 111 static inline void
 112 set_address_ipv6(address *addr, const ipv6_addr_and_prefix *ipv6) {
 113     set_address(addr, AT_IPv6, sizeof(ws_in6_addr), &ipv6->addr);
 114 }
 115
 116 /** Initialize an address from TVB data.
 117  *
 118  * Same as set_address but it takes a TVB and an offset. This is preferred
 119  * over passing the return value of tvb_get_ptr() to set_address().
 120  *
 121  * This calls tvb_get_ptr() (including throwing any exceptions) before
 122  * modifying the address.
 123  *
 124  * @param addr [in,out] The address to initialize.
 125  * @param addr_type [in] Address type.
 126  * @param tvb [in] Pointer to the TVB.
 127  * @param offset [in] Offset within the TVB.
 128  * @param addr_len [in] The length in bytes of the address data. For example, 4 for
 129  *                     AT_IPv4 or sizeof(ws_in6_addr) for AT_IPv6.
 130  */
 131 static inline void
 132 set_address_tvb(address *addr, int addr_type, int addr_len, tvbuff_t *tvb, int offset) {
 133     const void *p;
 134
 135     if (addr_len != 0) {
 136         /* Must not be AT_NONE - AT_NONE must have no data */
 137         ws_assert(addr_type != AT_NONE);
 138         p = tvb_get_ptr(tvb, offset, addr_len);
 139     } else
 140         p = NULL;
 141     set_address(addr, addr_type, addr_len, p);
 142 }
 143
 144 /** Initialize an address with the given values, allocating a new buffer
 145  * for the address data using wmem-scoped memory.
 146  *
 147  * @param scope [in] The lifetime of the allocated memory, e.g., pinfo->pool
 148  * @param addr [in,out] The address to initialize.
 149  * @param addr_type [in] Address type.
 150  * @param addr_len [in] The length in bytes of the address data. For example, 4 for
 151  *                     AT_IPv4 or sizeof(ws_in6_addr) for AT_IPv6.
 152  * @param addr_data [in] Pointer to the address data.
 153  */
 154 static inline void
 155 alloc_address_wmem(wmem_allocator_t *scope, address *addr,
 156                         int addr_type, int addr_len, const void *addr_data) {
 157     ws_assert(addr);
 158     clear_address(addr);
 159     addr->type = addr_type;
 160     if (addr_len == 0) {
 161         /* Zero length must mean no data */
 162         ws_assert(addr_data == NULL);
 163         /* Nothing to copy */
 164         return;
 165     }
 166     /* Must not be AT_NONE - AT_NONE must have no data */
 167     ws_assert(addr_type != AT_NONE);
 168     /* Make sure we *do* have data to copy */
 169     ws_assert(addr_data != NULL);
 170     addr->data = addr->priv = wmem_memdup(scope, addr_data, addr_len);
 171     addr->len = addr_len;
 172 }
 173
 174 /** Allocate an address from TVB data.
 175  *
 176  * Same as alloc_address_wmem but it takes a TVB and an offset.
 177  *
 178  * @param scope [in] The lifetime of the allocated memory, e.g., pinfo->pool
 179  * @param addr [in,out] The address to initialize.
 180  * @param addr_type [in] Address type.
 181  * @param addr_len [in] The length in bytes of the address data. For example, 4 for
 182  *                     AT_IPv4 or sizeof(ws_in6_addr) for AT_IPv6.
 183  * @param tvb [in] Pointer to the TVB.
 184  * @param offset [in] Offset within the TVB.
 185  */
 186 static inline void
 187 alloc_address_tvb(wmem_allocator_t *scope, address *addr,
 188                     int addr_type, int addr_len,  tvbuff_t *tvb, int offset) {
 189     const void *p;
 190
 191     p = tvb_get_ptr(tvb, offset, addr_len);
 192     alloc_address_wmem(scope, addr, addr_type, addr_len, p);
 193 }
 194
 195 /** Compare two addresses.
 196  *
 197  * @param addr1 [in] The first address to compare.
 198  * @param addr2 [in] The second address to compare.
 199  * @return 0 if the addresses are equal,
 200  *  A positive number if addr1 > addr2 in some nondefined metric,
 201  *  A negative number if addr1 < addr2 in some nondefined metric.
 202  */
 203 static inline int
 204 cmp_address(const address *addr1, const address *addr2) {
 205     if (addr1->type > addr2->type) return 1;
 206     if (addr1->type < addr2->type) return -1;
 207     if (addr1->len  > addr2->len) return 1;
 208     if (addr1->len  < addr2->len) return -1;
 209     if (addr1->len == 0) {
 210         /*
 211          * memcmp(NULL, NULL, 0) is *not* guaranteed to work, so
 212          * if both addresses are zero-length, don't compare them
 213          * (there's nothing to compare, so they're equal).
 214          */
 215         return 0;
 216     }
 217     return memcmp(addr1->data, addr2->data, addr1->len);
 218 }
 219
 220 /** Check two addresses for equality.
 221  *
 222  * Given two addresses, return "true" if they're equal, "false" otherwise.
 223  * Addresses are equal only if they have the same type and length; if the
 224  * length is zero, they are then equal, otherwise the data must be the
 225  * same.
 226  *
 227  * @param addr1 [in] The first address to compare.
 228  * @param addr2 [in] The second address to compare.
 229  * @return true if the addresses are equal, false otherwise.
 230  */
 231 static inline bool
 232 addresses_equal(const address *addr1, const address *addr2) {
 233     /*
 234      * memcmp(NULL, NULL, 0) is *not* guaranteed to work, so
 235      * if both addresses are zero-length, don't compare them
 236      * (there's nothing to compare, so they're equal).
 237      */
 238     if (addr1->type == addr2->type &&
 239         addr1->len == addr2->len &&
 240         (addr1->len == 0 ||
 241          memcmp(addr1->data, addr2->data, addr1->len) == 0))
 242         return true;
 243     return false;
 244 }
 245
 246 /** Check the data of two addresses for equality.
 247  *
 248  * Given two addresses, return "true" if they have the same length and,
 249  * their data is equal, "false" otherwise.
 250  * The address types are ignored. This can be used to compare custom
 251  * address types defined with address_type_dissector_register.
 252  *
 253  * @param addr1 [in] The first address to compare.
 254  * @param addr2 [in] The second address to compare.
 255  * @return true if the addresses are equal, false otherwise.
 256  */
 257 static inline bool
 258 addresses_data_equal(const address *addr1, const address *addr2) {
 259     if ( addr1->len == addr2->len
 260             && memcmp(addr1->data, addr2->data, addr1->len) == 0
 261             ) return true;
 262     return false;
 263 }
 264
 265 /** Perform a shallow copy of the address (both addresses point to the same
 266  * memory location).
 267  *
 268  * @param to [in,out] The destination address.
 269  * @param from [in] The source address.
 270  *
 271  * \warning Make sure 'from' memory stays valid for the lifetime of this object.
 272  * Also it's strongly recommended to use this function instead of copy-assign.
 273  */
 274 static inline void
 275 copy_address_shallow(address *to, const address *from) {
 276     set_address(to, from->type, from->len, from->data);
 277 }
 278
 279 /** Copy an address, allocating a new buffer for the address data
 280  *  using wmem-scoped memory.
 281  *
 282  * @param scope [in] The lifetime of the allocated memory, e.g., pinfo->pool
 283  * @param to [in,out] The destination address.
 284  * @param from [in] The source address.
 285  */
 286 static inline void
 287 copy_address_wmem(wmem_allocator_t *scope, address *to, const address *from) {
 288     alloc_address_wmem(scope, to, from->type, from->len, from->data);
 289 }
 290
 291 /** Copy an address, allocating a new buffer for the address data.
 292  *
 293  * @param to [in,out] The destination address.
 294  * @param from [in] The source address.
 295  */
 296 static inline void
 297 copy_address(address *to, const address *from) {
 298     copy_address_wmem(NULL, to, from);
 299 }
 300
 301 /** Free an address allocated with wmem-scoped memory.
 302  *
 303  * @param scope [in] The lifetime of the allocated memory, e.g., pinfo->pool
 304  * @param addr [in,out] The address whose data to free.
 305  */
 306 static inline void
 307 free_address_wmem(wmem_allocator_t *scope, address *addr) {
 308     /* Because many dissectors set 'type = AT_NONE' to mean clear we check for that */
 309     if (addr->type != AT_NONE && addr->len > 0 && addr->priv != NULL) {
 310         /* Make sure API use is correct */
 311         /* if priv is not null then data == priv */
 312         ws_assert(addr->data == addr->priv);
 313         wmem_free(scope, addr->priv);
 314     }
 315     clear_address(addr);
 316 }
 317
 318 /** Free an address.
 319  *
 320  * @param addr [in,out] The address whose data to free.
 321  */
 322 static inline void
 323 free_address(address *addr) {
 324     free_address_wmem(NULL, addr);
 325 }
 326
 327 /** Hash an address into a hash value (which must already have been set).
 328  *
 329  * @param hash_val The existing hash value.
 330  * @param addr The address to add.
 331  * @return The new hash value.
 332  */
 333 static inline unsigned
 334 add_address_to_hash(unsigned hash_val, const address *addr) {
 335     const uint8_t *hash_data = (const uint8_t *)(addr)->data;
 336     int idx;
 337
 338     for (idx = 0; idx < (addr)->len; idx++) {
 339         hash_val += hash_data[idx];
 340         hash_val += ( hash_val << 10 );
 341         hash_val ^= ( hash_val >> 6 );
 342     }
 343     return hash_val;
 344 }
 345
 346 /** Hash an address into a hash value (which must already have been set).
 347  *  64-bit version of add_address_to_hash().
 348  *
 349  * @param hash_val The existing hash value.
 350  * @param addr The address to add.
 351  * @return The new hash value.
 352  */
 353 static inline uint64_t
 354 add_address_to_hash64(uint64_t hash_val, const address *addr) {
 355     const uint8_t *hash_data = (const uint8_t *)(addr)->data;
 356     int idx;
 357
 358     for (idx = 0; idx < (addr)->len; idx++) {
 359         hash_val += hash_data[idx];
 360         hash_val += ( hash_val << 10 );
 361         hash_val ^= ( hash_val >> 6 );
 362     }
 363     return hash_val;
 364 }
 365
 366 WS_DLL_PUBLIC unsigned address_to_bytes(const address *addr, uint8_t *buf, unsigned buf_len);
 367
 368 /* Types of port numbers Wireshark knows about. */
 369 typedef enum {
 370     PT_NONE,            /* no port number */
 371     PT_SCTP,            /* SCTP */
 372     PT_TCP,             /* TCP */
 373     PT_UDP,             /* UDP */
 374     PT_DCCP,            /* DCCP */
 375     PT_IPX,             /* IPX sockets */
 376     PT_DDP,             /* DDP AppleTalk connection */
 377     PT_IDP,             /* XNS IDP sockets */
 378     PT_USB,             /* USB endpoint 0xffff means the host */
 379     PT_I2C,
 380     PT_IBQP,            /* Infiniband QP number */
 381     PT_BLUETOOTH,
 382     PT_IWARP_MPA,       /* iWarp MPA */
 383     PT_MCTP
 384 } port_type;
 385
 386 #ifdef __cplusplus
 387 }
 388 #endif /* __cplusplus */
 389
 390 #endif /* __ADDRESS_H__ */
 391
 392 /*
 393  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 394  *
 395  * Local variables:
 396  * c-basic-offset: 4
 397  * tab-width: 8
 398  * indent-tabs-mode: nil
 399  * End:
 400  *
 401  * vi: set shiftwidth=4 tabstop=8 expandtab:
 402  * :indentSize=4:tabSize=8:noTabs=true:
 403  */