Annotation of embedaddon/libnet/win32/wpdpack/Include/remote-ext.h, revision 1.1.1.1
1.1 misho 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>