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