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 468