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