contrib/libpcap/remote-ext.h

   1 /*
   2  * Copyright (c) 2002 - 2003
   3  * NetGroup, Politecnico di Torino (Italy)
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright
  11  * notice, this list of conditions and the following disclaimer.
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  * notice, this list of conditions and the following disclaimer in the
  14  * documentation and/or other materials provided with the distribution.
  15  * 3. Neither the name of the Politecnico di Torino nor the names of its
  16  * contributors may be used to endorse or promote products derived from
  17  * this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  *
  31  */
  32
  33
  34 #ifndef __REMOTE_EXT_H__
  35 #define __REMOTE_EXT_H__
  36
  37
  38 #ifndef HAVE_REMOTE
  39 #error Please do not include this file directly. Just define HAVE_REMOTE and then include pcap.h
  40 #endif
  41
  42 /*// Definition for Microsoft Visual Studio */
  43 #if _MSC_VER > 1000
  44 #pragma once
  45 #endif
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 /*
  52  * \file remote-ext.h
  53  *
  54  * The goal of this file it to include most of the new definitions that should be
  55  * placed into the pcap.h file.
  56  *
  57  * It includes all new definitions (structures and functions like pcap_open().
  58  * Some of the functions are not really a remote feature, but, right now,
  59  * they are placed here.
  60  */
  61
  62
  63
  64 /*// All this stuff is public */
  65 /*
  66  * \addtogroup remote_struct
  67  * \{
  68  */
  69
  70
  71
  72
  73 /*
  74  * \brief Defines the maximum buffer size in which address, port, interface names are kept.
  75  *
  76  * In case the adapter name or such is larger than this value, it is truncated.
  77  * This is not used by the user; however it must be aware that an hostname / interface
  78  * name longer than this value will be truncated.
  79  */
  80 #define PCAP_BUF_SIZE 1024
  81
  82
  83 /*
  84  * \addtogroup remote_source_ID
  85  * \{
  86  */
  87
  88
  89 /*
  90  * \brief Internal representation of the type of source in use (file,
  91  * remote/local interface).
  92  *
  93  * This indicates a file, i.e. the user want to open a capture from a local file.
  94  */
  95 #define PCAP_SRC_FILE 2
  96 /*
  97  * \brief Internal representation of the type of source in use (file,
  98  * remote/local interface).
  99  *
 100  * This indicates a local interface, i.e. the user want to open a capture from
 101  * a local interface. This does not involve the RPCAP protocol.
 102  */
 103 #define PCAP_SRC_IFLOCAL 3
 104 /*
 105  * \brief Internal representation of the type of source in use (file,
 106  * remote/local interface).
 107  *
 108  * This indicates a remote interface, i.e. the user want to open a capture from
 109  * an interface on a remote host. This does involve the RPCAP protocol.
 110  */
 111 #define PCAP_SRC_IFREMOTE 4
 112
 113 /*
 114  * \}
 115  */
 116
 117
 118
 119 /* \addtogroup remote_source_string
 120  *
 121  * The formats allowed by the pcap_open() are the following:
 122  * - file://path_and_filename [opens a local file]
 123  * - rpcap://devicename [opens the selected device devices available on the local host, without using the RPCAP protocol]
 124  * - rpcap://host/devicename [opens the selected device available on a remote host]
 125  * - rpcap://host:port/devicename [opens the selected device available on a remote host, using a non-standard port for RPCAP]
 126  * - adaptername [to open a local adapter; kept for compability, but it is strongly discouraged]
 127  * - (NULL) [to open the first local adapter; kept for compability, but it is strongly discouraged]
 128  *
 129  * The formats allowed by the pcap_findalldevs_ex() are the following:
 130  * - file://folder/ [lists all the files in the given folder]
 131  * - rpcap:// [lists all local adapters]
 132  * - rpcap://host:port/ [lists the devices available on a remote host]
 133  *
 134  * Referring to the 'host' and 'port' parameters, they can be either numeric or literal. Since
 135  * IPv6 is fully supported, these are the allowed formats:
 136  *
 137  * - host (literal): e.g. host.foo.bar
 138  * - host (numeric IPv4): e.g. 10.11.12.13
 139  * - host (numeric IPv4, IPv6 style): e.g. [10.11.12.13]
 140  * - host (numeric IPv6): e.g. [1:2:3::4]
 141  * - port: can be either numeric (e.g. '80') or literal (e.g. 'http')
 142  *
 143  * Here you find some allowed examples:
 144  * - rpcap://host.foo.bar/devicename [everything literal, no port number]
 145  * - rpcap://host.foo.bar:1234/devicename [everything literal, with port number]
 146  * - rpcap://10.11.12.13/devicename [IPv4 numeric, no port number]
 147  * - rpcap://10.11.12.13:1234/devicename [IPv4 numeric, with port number]
 148  * - rpcap://[10.11.12.13]:1234/devicename [IPv4 numeric with IPv6 format, with port number]
 149  * - rpcap://[1:2:3::4]/devicename [IPv6 numeric, no port number]
 150  * - rpcap://[1:2:3::4]:1234/devicename [IPv6 numeric, with port number]
 151  * - rpcap://[1:2:3::4]:http/devicename [IPv6 numeric, with literal port number]
 152  *
 153  * \{
 154  */
 155
 156
 157 /*
 158  * \brief String that will be used to determine the type of source in use (file,
 159  * remote/local interface).
 160  *
 161  * This string will be prepended to the interface name in order to create a string
 162  * that contains all the information required to open the source.
 163  *
 164  * This string indicates that the user wants to open a capture from a local file.
 165  */
 166 #define PCAP_SRC_FILE_STRING "file://"
 167 /*
 168  * \brief String that will be used to determine the type of source in use (file,
 169  * remote/local interface).
 170  *
 171  * This string will be prepended to the interface name in order to create a string
 172  * that contains all the information required to open the source.
 173  *
 174  * This string indicates that the user wants to open a capture from a network interface.
 175  * This string does not necessarily involve the use of the RPCAP protocol. If the
 176  * interface required resides on the local host, the RPCAP protocol is not involved
 177  * and the local functions are used.
 178  */
 179 #define PCAP_SRC_IF_STRING "rpcap://"
 180
 181 /*
 182  * \}
 183  */
 184
 185
 186
 187
 188
 189 /*
 190  * \addtogroup remote_open_flags
 191  * \{
 192  */
 193
 194 /*
 195  * \brief Defines if the adapter has to go in promiscuous mode.
 196  *
 197  * It is '1' if you have to open the adapter in promiscuous mode, '0' otherwise.
 198  * Note that even if this parameter is false, the interface could well be in promiscuous
 199  * mode for some other reason (for example because another capture process with
 200  * promiscuous mode enabled is currently using that interface).
 201  * On on Linux systems with 2.2 or later kernels (that have the "any" device), this
 202  * flag does not work on the "any" device; if an argument of "any" is supplied,
 203  * the 'promisc' flag is ignored.
 204  */
 205 #define PCAP_OPENFLAG_PROMISCUOUS               1
 206
 207 /*
 208  * \brief Defines if the data transfer (in case of a remote
 209  * capture) has to be done with UDP protocol.
 210  *
 211  * If it is '1' if you want a UDP data connection, '0' if you want
 212  * a TCP data connection; control connection is always TCP-based.
 213  * A UDP connection is much lighter, but it does not guarantee that all
 214  * the captured packets arrive to the client workstation. Moreover,
 215  * it could be harmful in case of network congestion.
 216  * This flag is meaningless if the source is not a remote interface.
 217  * In that case, it is simply ignored.
 218  */
 219 #define PCAP_OPENFLAG_DATATX_UDP                        2
 220
 221
 222 /*
 223  * \brief Defines if the remote probe will capture its own generated traffic.
 224  *
 225  * In case the remote probe uses the same interface to capture traffic and to send
 226  * data back to the caller, the captured traffic includes the RPCAP traffic as well.
 227  * If this flag is turned on, the RPCAP traffic is excluded from the capture, so that
 228  * the trace returned back to the collector is does not include this traffic.
 229  */
 230 #define PCAP_OPENFLAG_NOCAPTURE_RPCAP   4
 231
 232 /*
 233  * \brief Defines if the local adapter will capture its own generated traffic.
 234  *
 235  * This flag tells the underlying capture driver to drop the packets that were sent by itself.
 236  * This is useful when building applications like bridges, that should ignore the traffic
 237  * they just sent.
 238  */
 239 #define PCAP_OPENFLAG_NOCAPTURE_LOCAL   8
 240
 241 /*
 242  * \brief This flag configures the adapter for maximum responsiveness.
 243  *
 244  * In presence of a large value for nbytes, WinPcap waits for the arrival of several packets before
 245  * copying the data to the user. This guarantees a low number of system calls, i.e. lower processor usage,
 246  * i.e. better performance, which is good for applications like sniffers. If the user sets the
 247  * PCAP_OPENFLAG_MAX_RESPONSIVENESS flag, the capture driver will copy the packets as soon as the application
 248  * is ready to receive them. This is suggested for real time applications (like, for example, a bridge)
 249  * that need the best responsiveness.
 250  */
 251 #define PCAP_OPENFLAG_MAX_RESPONSIVENESS        16
 252
 253 /*
 254  * \}
 255  */
 256
 257
 258 /*
 259  * \addtogroup remote_samp_methods
 260  * \{
 261  */
 262
 263 /*
 264  *\brief No sampling has to be done on the current capture.
 265  *
 266  * In this case, no sampling algorithms are applied to the current capture.
 267  */
 268 #define PCAP_SAMP_NOSAMP        0
 269
 270 /*
 271  * \brief It defines that only 1 out of N packets must be returned to the user.
 272  *
 273  * In this case, the 'value' field of the 'pcap_samp' structure indicates the
 274  * number of packets (minus 1) that must be discarded before one packet got accepted.
 275  * In other words, if 'value = 10', the first packet is returned to the caller, while
 276  * the following 9 are discarded.
 277  */
 278 #define PCAP_SAMP_1_EVERY_N     1
 279
 280 /*
 281  * \brief It defines that we have to return 1 packet every N milliseconds.
 282  *
 283  * In this case, the 'value' field of the 'pcap_samp' structure indicates the 'waiting
 284  * time' in milliseconds before one packet got accepted.
 285  * In other words, if 'value = 10', the first packet is returned to the caller; the next
 286  * returned one will be the first packet that arrives when 10ms have elapsed.
 287  */
 288 #define PCAP_SAMP_FIRST_AFTER_N_MS 2
 289
 290 /*
 291  * \}
 292  */
 293
 294
 295 /*
 296  * \addtogroup remote_auth_methods
 297  * \{
 298  */
 299
 300 /*
 301  * \brief It defines the NULL authentication.
 302  *
 303  * This value has to be used within the 'type' member of the pcap_rmtauth structure.
 304  * The 'NULL' authentication has to be equal to 'zero', so that old applications
 305  * can just put every field of struct pcap_rmtauth to zero, and it does work.
 306  */
 307 #define RPCAP_RMTAUTH_NULL 0
 308 /*
 309  * \brief It defines the username/password authentication.
 310  *
 311  * With this type of authentication, the RPCAP protocol will use the username/
 312  * password provided to authenticate the user on the remote machine. If the
 313  * authentication is successful (and the user has the right to open network devices)
 314  * the RPCAP connection will continue; otherwise it will be dropped.
 315  *
 316  * This value has to be used within the 'type' member of the pcap_rmtauth structure.
 317  */
 318 #define RPCAP_RMTAUTH_PWD 1
 319
 320 /*
 321  * \}
 322  */
 323
 324
 325
 326
 327 /*
 328  * \brief This structure keeps the information needed to autheticate
 329  * the user on a remote machine.
 330  *
 331  * The remote machine can either grant or refuse the access according
 332  * to the information provided.
 333  * In case the NULL authentication is required, both 'username' and
 334  * 'password' can be NULL pointers.
 335  *
 336  * This structure is meaningless if the source is not a remote interface;
 337  * in that case, the functions which requires such a structure can accept
 338  * a NULL pointer as well.
 339  */
 340 struct pcap_rmtauth
 341 {
 342         /*
 343          * \brief Type of the authentication required.
 344          *
 345          * In order to provide maximum flexibility, we can support different types
 346          * of authentication based on the value of this 'type' variable. The currently
 347          * supported authentication methods are defined into the
 348          * \link remote_auth_methods Remote Authentication Methods Section\endlink.
 349          */
 350         int type;
 351         /*
 352          * \brief Zero-terminated string containing the username that has to be
 353          * used on the remote machine for authentication.
 354          *
 355          * This field is meaningless in case of the RPCAP_RMTAUTH_NULL authentication
 356          * and it can be NULL.
 357          */
 358         char *username;
 359         /*
 360          * \brief Zero-terminated string containing the password that has to be
 361          * used on the remote machine for authentication.
 362          *
 363          * This field is meaningless in case of the RPCAP_RMTAUTH_NULL authentication
 364          * and it can be NULL.
 365          */
 366         char *password;
 367 };
 368
 369
 370 /*
 371  * \brief This structure defines the information related to sampling.
 372  *
 373  * In case the sampling is requested, the capturing device should read
 374  * only a subset of the packets coming from the source. The returned packets depend
 375  * on the sampling parameters.
 376  *
 377  * \warning The sampling process is applied <strong>after</strong> the filtering process.
 378  * In other words, packets are filtered first, then the sampling process selects a
 379  * subset of the 'filtered' packets and it returns them to the caller.
 380  */
 381 struct pcap_samp
 382 {
 383         /*
 384          * Method used for sampling. Currently, the supported methods are listed in the
 385          * \link remote_samp_methods Sampling Methods Section\endlink.
 386          */
 387         int method;
 388
 389         /*
 390          * This value depends on the sampling method defined. For its meaning, please check
 391          * at the \link remote_samp_methods Sampling Methods Section\endlink.
 392          */
 393         int value;
 394 };
 395
 396
 397
 398
 399 // Maximum length of an host name (needed for the RPCAP active mode)
 400 #define RPCAP_HOSTLIST_SIZE 1024
 401
 402
 403 /*
 404  * \}
 405  */ // end of public documentation
 406
 407
 408 // Exported functions
 409
 410
 411
 412 /*
 413  * \name New WinPcap functions
 414  *
 415  * This section lists the new functions that are able to help considerably in writing
 416  * WinPcap programs because of their easiness of use.
 417  */
 418 // \{
 419 PCAP_API pcap_t *pcap_open(const char *source, int snaplen, int flags, int read_timeout, struct pcap_rmtauth *auth, char *errbuf);
 420 PCAP_API int pcap_createsrcstr(char *source, int type, const char *host, const char *port, const char *name, char *errbuf);
 421 PCAP_API int pcap_parsesrcstr(const char *source, int *type, char *host, char *port, char *name, char *errbuf);
 422 PCAP_API int pcap_findalldevs_ex(char *source, struct pcap_rmtauth *auth, pcap_if_t **alldevs, char *errbuf);
 423 PCAP_API struct pcap_samp *pcap_setsampling(pcap_t *p);
 424
 425 // \}
 426 // End of new WinPcap functions
 427
 428 /*
 429  * \name Remote Capture functions
 430  */
 431
 432 /*
 433  * Some minor differences between UN*X sockets and and Winsock sockets.
 434  */
 435 #ifndef _WIN32
 436   /*!
 437    * \brief In Winsock, a socket handle is of type SOCKET; in UN*X, it's
 438    * a file descriptor, and therefore a signed integer.
 439    * We define SOCKET to be a signed integer on UN*X, so that it can
 440    * be used on both platforms.
 441    */
 442   #define SOCKET int
 443
 444   /*!
 445    * \brief In Winsock, the error return if socket() fails is INVALID_SOCKET;
 446    * in UN*X, it's -1.
 447    * We define INVALID_SOCKET to be -1 on UN*X, so that it can be used on
 448    * both platforms.
 449    */
 450   #define INVALID_SOCKET -1
 451 #endif
 452
 453 // \{
 454 PCAP_API SOCKET pcap_remoteact_accept(const char *address, const char *port, const char *hostlist, char *connectinghost, struct pcap_rmtauth *auth, char *errbuf);
 455 PCAP_API int pcap_remoteact_list(char *hostlist, char sep, int size, char *errbuf);
 456 PCAP_API int pcap_remoteact_close(const char *host, char *errbuf);
 457 PCAP_API void pcap_remoteact_cleanup();
 458 // \}
 459 // End of remote capture functions
 460
 461 #ifdef __cplusplus
 462 }
 463 #endif
 464
 465
 466 #endif
 467