/* * Copyright (c) 2002 - 2003 * NetGroup, Politecnico di Torino (Italy) * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of the Politecnico di Torino nor the names of its * contributors may be used to endorse or promote products derived from * this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE * */ #ifndef __REMOTE_EXT_H__ #define __REMOTE_EXT_H__ #ifndef HAVE_REMOTE #error Please do not include this file directly. Just define HAVE_REMOTE and then include pcap.h #endif /* Definition for Microsoft Visual Studio */ #if _MSC_VER > 1000 #pragma once #endif #ifdef __cplusplus extern "C" { #endif /*! * \file remote-ext.h * * The goal of this file it to include most of the new definitions that should be * placed into the pcap.h file. * * It includes all new definitions (structures and functions like pcap_open(). * Some of the functions are not really a remote feature, but, right now, * they are placed here. */ /* All this stuff is public */ /*! \addtogroup remote_struct \{ */ /*! * \brief Defines the maximum buffer size in which address, port, interface names are kept. * * In case the adapter name or such is larger than this value, it is truncated. * This is not used by the user; however it must be aware that an hostname / interface * name longer than this value will be truncated. */ #define PCAP_BUF_SIZE 1024 /*! \addtogroup remote_source_ID \{ */ /*! * \brief Internal representation of the type of source in use (file, * remote/local interface). * * This indicates a file, i.e. the user want to open a capture from a local file. */ #define PCAP_SRC_FILE 2 /*! * \brief Internal representation of the type of source in use (file, * remote/local interface). * * This indicates a local interface, i.e. the user want to open a capture from * a local interface. This does not involve the RPCAP protocol. */ #define PCAP_SRC_IFLOCAL 3 /*! * \brief Internal representation of the type of source in use (file, * remote/local interface). * * This indicates a remote interface, i.e. the user want to open a capture from * an interface on a remote host. This does involve the RPCAP protocol. */ #define PCAP_SRC_IFREMOTE 4 /*! \} */ /*! \addtogroup remote_source_string * * The formats allowed by the pcap_open() are the following: * - file://path_and_filename [opens a local file] * - rpcap://devicename [opens the selected device devices available on the local host, without using the RPCAP protocol] * - rpcap://host/devicename [opens the selected device available on a remote host] * - rpcap://host:port/devicename [opens the selected device available on a remote host, using a non-standard port for RPCAP] * - adaptername [to open a local adapter; kept for compability, but it is strongly discouraged] * - (NULL) [to open the first local adapter; kept for compability, but it is strongly discouraged] * * The formats allowed by the pcap_findalldevs_ex() are the following: * - file://folder/ [lists all the files in the given folder] * - rpcap:// [lists all local adapters] * - rpcap://host:port/ [lists the devices available on a remote host] * * Referring to the 'host' and 'port' paramters, they can be either numeric or literal. Since * IPv6 is fully supported, these are the allowed formats: * * - host (literal): e.g. host.foo.bar * - host (numeric IPv4): e.g. 10.11.12.13 * - host (numeric IPv4, IPv6 style): e.g. [10.11.12.13] * - host (numeric IPv6): e.g. [1:2:3::4] * - port: can be either numeric (e.g. '80') or literal (e.g. 'http') * * Here you find some allowed examples: * - rpcap://host.foo.bar/devicename [everything literal, no port number] * - rpcap://host.foo.bar:1234/devicename [everything literal, with port number] * - rpcap://10.11.12.13/devicename [IPv4 numeric, no port number] * - rpcap://10.11.12.13:1234/devicename [IPv4 numeric, with port number] * - rpcap://[10.11.12.13]:1234/devicename [IPv4 numeric with IPv6 format, with port number] * - rpcap://[1:2:3::4]/devicename [IPv6 numeric, no port number] * - rpcap://[1:2:3::4]:1234/devicename [IPv6 numeric, with port number] * - rpcap://[1:2:3::4]:http/devicename [IPv6 numeric, with literal port number] * \{ */ /*! * \brief String that will be used to determine the type of source in use (file, * remote/local interface). * * This string will be prepended to the interface name in order to create a string * that contains all the information required to open the source. * * This string indicates that the user wants to open a capture from a local file. */ #define PCAP_SRC_FILE_STRING "file://" /*! * \brief String that will be used to determine the type of source in use (file, * remote/local interface). * * This string will be prepended to the interface name in order to create a string * that contains all the information required to open the source. * * This string indicates that the user wants to open a capture from a network interface. * This string does not necessarily involve the use of the RPCAP protocol. If the * interface required resides on the local host, the RPCAP protocol is not involved * and the local functions are used. */ #define PCAP_SRC_IF_STRING "rpcap://" /*! \} */ /*! * \addtogroup remote_open_flags \{ */ /*! * \brief Defines if the adapter has to go in promiscuous mode. * * It is '1' if you have to open the adapter in promiscuous mode, '0' otherwise. * Note that even if this parameter is false, the interface could well be in promiscuous * mode for some other reason (for example because another capture process with * promiscuous mode enabled is currently using that interface). * On on Linux systems with 2.2 or later kernels (that have the "any" device), this * flag does not work on the "any" device; if an argument of "any" is supplied, * the 'promisc' flag is ignored. */ #define PCAP_OPENFLAG_PROMISCUOUS 1 /*! * \brief Defines if the data transfer (in case of a remote * capture) has to be done with UDP protocol. * * If it is '1' if you want a UDP data connection, '0' if you want * a TCP data connection; control connection is always TCP-based. * A UDP connection is much lighter, but it does not guarantee that all * the captured packets arrive to the client workstation. Moreover, * it could be harmful in case of network congestion. * This flag is meaningless if the source is not a remote interface. * In that case, it is simply ignored. */ #define PCAP_OPENFLAG_DATATX_UDP 2 /*! * \brief Defines if the remote probe will capture its own generated traffic. * * In case the remote probe uses the same interface to capture traffic and to send * data back to the caller, the captured traffic includes the RPCAP traffic as well. * If this flag is turned on, the RPCAP traffic is excluded from the capture, so that * the trace returned back to the collector is does not include this traffic. */ #define PCAP_OPENFLAG_NOCAPTURE_RPCAP 4 /*! * \brief Defines if the local adapter will capture its own generated traffic. * * This flag tells the underlying capture driver to drop the packets that were sent by itself. * This is useful when building applications like bridges, that should ignore the traffic * they just sent. */ #define PCAP_OPENFLAG_NOCAPTURE_LOCAL 8 /*! * \brief This flag configures the adapter for maximum responsiveness. * * In presence of a large value for nbytes, WinPcap waits for the arrival of several packets before * copying the data to the user. This guarantees a low number of system calls, i.e. lower processor usage, * i.e. better performance, which is good for applications like sniffers. If the user sets the * PCAP_OPENFLAG_MAX_RESPONSIVENESS flag, the capture driver will copy the packets as soon as the application * is ready to receive them. This is suggested for real time applications (like, for example, a bridge) * that need the best responsiveness.*/ #define PCAP_OPENFLAG_MAX_RESPONSIVENESS 16 /*! \} */ /*! * \addtogroup remote_samp_methods \{ */ /*! * \brief No sampling has to be done on the current capture. * * In this case, no sampling algorithms are applied to the current capture. */ #define PCAP_SAMP_NOSAMP 0 /*! * \brief It defines that only 1 out of N packets must be returned to the user. * * In this case, the 'value' field of the 'pcap_samp' structure indicates the * number of packets (minus 1) that must be discarded before one packet got accepted. * In other words, if 'value = 10', the first packet is returned to the caller, while * the following 9 are discarded. */ #define PCAP_SAMP_1_EVERY_N 1 /*! * \brief It defines that we have to return 1 packet every N milliseconds. * * In this case, the 'value' field of the 'pcap_samp' structure indicates the 'waiting * time' in milliseconds before one packet got accepted. * In other words, if 'value = 10', the first packet is returned to the caller; the next * returned one will be the first packet that arrives when 10ms have elapsed. */ #define PCAP_SAMP_FIRST_AFTER_N_MS 2 /*! \} */ /*! * \addtogroup remote_auth_methods \{ */ /*! * \brief It defines the NULL authentication. * * This value has to be used within the 'type' member of the pcap_rmtauth structure. * The 'NULL' authentication has to be equal to 'zero', so that old applications * can just put every field of struct pcap_rmtauth to zero, and it does work. */ #define RPCAP_RMTAUTH_NULL 0 /*! * \brief It defines the username/password authentication. * * With this type of authentication, the RPCAP protocol will use the username/ * password provided to authenticate the user on the remote machine. If the * authentication is successful (and the user has the right to open network devices) * the RPCAP connection will continue; otherwise it will be dropped. * * This value has to be used within the 'type' member of the pcap_rmtauth structure. */ #define RPCAP_RMTAUTH_PWD 1 /*! \} */ /*! * * \brief This structure keeps the information needed to authenticate * the user on a remote machine. * * The remote machine can either grant or refuse the access according * to the information provided. * In case the NULL authentication is required, both 'username' and * 'password' can be NULL pointers. * * This structure is meaningless if the source is not a remote interface; * in that case, the functions which requires such a structure can accept * a NULL pointer as well. */ struct pcap_rmtauth { /*! * \brief Type of the authentication required. * * In order to provide maximum flexibility, we can support different types * of authentication based on the value of this 'type' variable. The currently * supported authentication methods are defined into the * \link remote_auth_methods Remote Authentication Methods Section\endlink. * */ int type; /*! * \brief Zero-terminated string containing the username that has to be * used on the remote machine for authentication. * * This field is meaningless in case of the RPCAP_RMTAUTH_NULL authentication * and it can be NULL. */ char * username; /*! * \brief Zero-terminated string containing the password that has to be * used on the remote machine for authentication. * * This field is meaningless in case of the RPCAP_RMTAUTH_NULL authentication * and it can be NULL. */ char * password; }; /*! * \brief This structure defines the information related to sampling. * * In case the sampling is requested, the capturing device should read * only a subset of the packets coming from the source. The returned packets depend * on the sampling parameters. * * \warning The sampling process is applied after the filtering process. * In other words, packets are filtered first, then the sampling process selects a * subset of the 'filtered' packets and it returns them to the caller. */ struct pcap_samp { /*! * Method used for sampling. Currently, the supported methods are listed in the * \link remote_samp_methods Sampling Methods Section\endlink. */ int method; /*! * This value depends on the sampling method defined. For its meaning, please check * at the \link remote_samp_methods Sampling Methods Section\endlink. */ int value; }; /*! Maximum length of an host name (needed for the RPCAP active mode) */ #define RPCAP_HOSTLIST_SIZE 1024 /*! \} *//* end of public documentation */ /* Exported functions */ /** \name New WinPcap functions * * This section lists the new functions that are able to help considerably in writing * WinPcap programs because of their easiness of use. */ /*\{ */ pcap_t * pcap_open( const char * source, int snaplen, int flags, int read_timeout, struct pcap_rmtauth * auth, char * errbuf ); int pcap_createsrcstr( char * source, int type, const char * host, const char * port, const char * name, char * errbuf ); int pcap_parsesrcstr( const char * source, int * type, char * host, char * port, char * name, char * errbuf ); int pcap_findalldevs_ex( char * source, struct pcap_rmtauth * auth, pcap_if_t ** alldevs, char * errbuf ); struct pcap_samp * pcap_setsampling( pcap_t * p ); /*\} */ /* End of new winpcap functions */ /** \name Remote Capture functions */ /*\{ */ SOCKET pcap_remoteact_accept( const char * address, const char * port, const char * hostlist, char * connectinghost, struct pcap_rmtauth * auth, char * errbuf ); int pcap_remoteact_list( char * hostlist, char sep, int size, char * errbuf ); int pcap_remoteact_close( const char * host, char * errbuf ); void pcap_remoteact_cleanup(); /*\} */ /* End of remote capture functions */ #ifdef __cplusplus } #endif #endif /* ifndef __REMOTE_EXT_H__ */