• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2002 - 2005 NetGroup, Politecnico di Torino (Italy)
3  * Copyright (c) 2005 - 2008 CACE Technologies, Davis (California)
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, CACE Technologies
16  * nor the names of its contributors may be used to endorse or promote
17  * products derived from this software without specific prior written
18  * permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  */
33 
34 #ifndef __RPCAP_PROTOCOL_H__
35 #define __RPCAP_PROTOCOL_H__
36 
37 #define RPCAP_DEFAULT_NETPORT "2002" /* Default port on which the RPCAP daemon is waiting for connections. */
38 /* Default port on which the client workstation is waiting for connections in case of active mode. */
39 #define RPCAP_DEFAULT_NETPORT_ACTIVE "2003"
40 #define RPCAP_DEFAULT_NETADDR ""	/* Default network address on which the RPCAP daemon binds to. */
41 
42 /*
43  * Minimum and maximum supported versions of the protocol.
44  *
45  * If new message types are added, the protocol version MUST be changed,
46  * so that a client knows, from the negotiated protocol version, what
47  * messages can be sent to the server.
48  *
49  * If the format of an existing message type is changed, the protocol
50  * version MUST be changed, so that each side knows, from the negotiated
51  * protocol version, what format should be used.
52  *
53  * The RPCAP_MSG_ERROR format MUST not change, as it's used to, among
54  * other things, report "incorrect version number" errors, where, if
55  * the format changed, the sender of the message might not know what
56  * versions the recipient would understand, or might know a version
57  * they support (the version number they sent) but might not know
58  * the format of the message in that version.
59  *
60  * Other message versions SHOULD not change, as that would complicate
61  * the process of interpreting the message, making it version-dependent.
62  * Introducing a new message with a new format is preferable.
63  *
64  * Version negotiation is done as part of the authentication process:
65  *
66  * The client sends an authentication request, with the version number
67  * in the request being the maximum version it supports.
68  *
69  * If the server supports that version, it attempts to authenticate the
70  * client, and replies as appropriate, with the version number in the
71  * reply being that version.
72  *
73  * If the server doesn't support that version because it's too large,
74  * it replies with a RPCAP_MSG_ERROR message, with the maximum version
75  * they support as the version number in the reply, and with the error
76  * code being PCAP_ERR_WRONGVER.
77  *
78  * If the server doesn't support that version because it's too small,
79  * it replies with a RPCAP_MSG_ERROR message, with that version as
80  * the version number in the reply, and with the error code being
81  * PCAP_ERR_WRONGVER.
82  *
83  * If the client supports that version, it retries the authentication
84  * with that version and, if that fails for any reason, including
85  * PCAP_ERR_WRONGVER, fails.  Otherwise, it fails, telling its caller
86  * that there's no version that both support.
87  *
88  * This requires that the set of versions supported by a client or
89  * server be a range of integers, with no gaps.  Thus:
90  *
91  * the client's version set is [Cmin, Cmax], with Cmin <= Cmax;
92  *
93  * the server's version set is [Smin, Smax], with Smin <= Smax;
94  *
95  * the client sends Cmax as the version number in the initial
96  * authentication request;
97  *
98  * if the server doesn't support the version sent by the client,
99  * either Smax < Cmax or Smin > Cmax (because the client sent Cmax
100  * to the server, and the server doesn't support it);
101  *
102  * if Smax < Cmax:
103  *
104  *    the server sends Smax as the version number in the RPCAP_MSG_ERROR/
105  *    PCAP_ERR_WRONGVER message - the client will accept this because
106  *    Cmax != 0, as these numbers are unsigned, and this means that
107  *    this isn't an old client that rejects all messages with a non-zero
108  *    version number, it's a new client that accepts RPCAP_MSG_ERROR
109  *    messages no matter what the version is;
110  *
111  *    if Smax >= Cmin, both the client and the server can use it, and
112  *    the client retries with Smax;
113  *
114  *    if Smax < Cmin, there is no version the client and server can
115  *    both support.
116  *
117  * if Smin > Cmax:
118  *
119  *    the server sends Cmax as the version number in the RPCAP_MSG_ERROR/
120  *    PCAP_ERR_WRONGVER message - the client will accept this because
121  *    Cmax is a valid client version number.
122  *
123  *    the client will retry with Cmax, get the same version failure,
124  *    and report that there is no version the client and server can
125  *    both support (as the version sets are disjoint).
126  *
127  * Old negotiation-unaware clients just send version 0 and, if they
128  * get back PCAP_ERR_WRONGVER, treat it as a fatal error.  This
129  * means they'll fail to talk to any server that can't handle
130  * version 0, which is the appropriate thing to do, as they can
131  * only use version 0.
132  *
133  * Old negotiation-unaware servers fail if they get a version other
134  * than 0, sending back PCAP_ERR_WRONGVER with version 0, which is
135  * the only version, and thus both the minimum and maximum version,
136  * they support.  The client will either fail if it doesn't support
137  * version 0, or will retry with version 0 and succeed, so it will
138  * fail with servers that can't handle version 0 or will negotiate
139  * version 0 with servers that can handle version 0.
140  */
141 #define RPCAP_MIN_VERSION 0
142 #define RPCAP_MAX_VERSION 0
143 
144 /*
145  * Version numbers are unsigned, so if RPCAP_MIN_VERSION is 0, they
146  * are >= the minimum version, by definition; don't check against
147  * RPCAP_MIN_VERSION, as you may get compiler warnings that the
148  * comparison will always succeed.
149  */
150 #if RPCAP_MIN_VERSION == 0
151 #define RPCAP_VERSION_IS_SUPPORTED(v)	((v) <= RPCAP_MAX_VERSION)
152 #else
153 #define RPCAP_VERSION_IS_SUPPORTED(v)	\
154 	((v) >= RPCAP_MIN_VERSION && (v) <= RPCAP_MAX_VERSION)
155 #endif
156 
157 /*
158  * Separators used for the host list.
159  *
160  * It is used:
161  * - by the rpcapd daemon, when you types a list of allowed connecting hosts
162  * - by the rpcap client in active mode, when the client waits for incoming
163  * connections from other hosts
164  */
165 #define RPCAP_HOSTLIST_SEP " ,;\n\r"
166 
167 /*********************************************************
168  *                                                       *
169  * Protocol messages formats                             *
170  *                                                       *
171  *********************************************************/
172 /*
173  * WARNING: This file defines some structures that are used to transfer
174  * data on the network.
175  * Note that your compiler MUST not insert padding into these structures
176  * for better alignment.
177  * These structures have been created in order to be correctly aligned to
178  * a 32-bit boundary, but be careful in any case.
179  */
180 
181 /*
182  * WARNING: These typedefs MUST be of a specific size.
183  * You might have to change them on your platform.
184  *
185  * XXX - use the C99 types?  Microsoft's newer versions of Visual Studio
186  * support them.
187  */
188 typedef unsigned char uint8;	/* 8-bit unsigned integer */
189 typedef unsigned short uint16;	/* 16-bit unsigned integer */
190 typedef unsigned int uint32;	/* 32-bit unsigned integer */
191 typedef int int32;		/* 32-bit signed integer */
192 
193 /* Common header for all the RPCAP messages */
194 struct rpcap_header
195 {
196 	uint8 ver;	/* RPCAP version number */
197 	uint8 type;	/* RPCAP message type (error, findalldevs, ...) */
198 	uint16 value;	/* Message-dependent value (not always used) */
199 	uint32 plen;	/* Length of the payload of this RPCAP message */
200 };
201 
202 /* Format of the message for the interface description (findalldevs command) */
203 struct rpcap_findalldevs_if
204 {
205 	uint16 namelen;	/* Length of the interface name */
206 	uint16 desclen;	/* Length of the interface description */
207 	uint32 flags;	/* Interface flags */
208 	uint16 naddr;	/* Number of addresses */
209 	uint16 dummy;	/* Must be zero */
210 };
211 
212 /*
213  * Format of an address as sent over the wire.
214  *
215  * Do *NOT* use struct sockaddr_storage, as the layout for that is
216  * machine-dependent.
217  *
218  * RFC 2553 gives two sample layouts, both of which are 128 bytes long,
219  * both of which are aligned on an 8-byte boundary, and both of which
220  * have 2 bytes before the address data.
221  *
222  * However, one has a 2-byte address family value at the beginning
223  * and the other has a 1-byte address length value and a 1-byte
224  * address family value; this reflects the fact that the original
225  * BSD sockaddr structure had a 2-byte address family value, which
226  * was later changed to a 1-byte address length value and a 1-byte
227  * address family value, when support for variable-length OSI
228  * network-layer addresses was added.
229  *
230  * Furthermore, Solaris's struct sockaddr_storage is 256 bytes
231  * long.
232  *
233  * This structure is supposed to be aligned on an 8-byte boundary;
234  * the message header is 8 bytes long, so we don't have to do
235  * anything to ensure it's aligned on that boundary within a packet,
236  * so we just define it as 128 bytes long, with a 2-byte address
237  * family.  (We only support IPv4 and IPv6 addresses, which are fixed-
238  * length.)  That way, it's the same size as sockaddr_storage on
239  * Windows, and it'll look like what an older Windows client will
240  * expect.
241  *
242  * In addition, do *NOT* use the host's AF_ value for an address,
243  * as the value for AF_INET6 is machine-dependent.  We use the
244  * Windows value, so it'll look like what an older Windows client
245  * will expect.
246  *
247  * (The Windows client is the only one that has been distributed
248  * as a standard part of *pcap; UN*X clients are probably built
249  * from source by the user or administrator, so they're in a
250  * better position to upgrade an old client.  Therefore, we
251  * try to make what goes over the wire look like what comes
252  * from a Windows server.)
253  */
254 struct rpcap_sockaddr
255 {
256 	uint16	family;			/* Address family */
257 	char	data[128-2];		/* Data */
258 };
259 
260 /*
261  * Format of an IPv4 address as sent over the wire.
262  */
263 #define RPCAP_AF_INET	2		/* Value on all OSes */
264 struct rpcap_sockaddr_in
265 {
266 	uint16	family;			/* Address family */
267 	uint16	port;			/* Port number */
268 	uint32	addr;			/* IPv4 address */
269 	uint8	zero[8];		/* Padding */
270 };
271 
272 /*
273  * Format of an IPv6 address as sent over the wire.
274  */
275 #define RPCAP_AF_INET6	23		/* Value on Windows */
276 struct rpcap_sockaddr_in6
277 {
278 	uint16	family;			/* Address family */
279 	uint16	port;			/* Port number */
280 	uint32	flowinfo;		/* IPv6 flow information */
281 	uint8	addr[16];		/* IPv6 address */
282 	uint32	scope_id;		/* Scope zone index */
283 };
284 
285 /* Format of the message for the address listing (findalldevs command) */
286 struct rpcap_findalldevs_ifaddr
287 {
288 	struct rpcap_sockaddr addr;		/* Network address */
289 	struct rpcap_sockaddr netmask;		/* Netmask for that address */
290 	struct rpcap_sockaddr broadaddr;	/* Broadcast address for that address */
291 	struct rpcap_sockaddr dstaddr;		/* P2P destination address for that address */
292 };
293 
294 /*
295  * \brief Format of the message of the connection opening reply (open command).
296  *
297  * This structure transfers over the network some of the values useful on the client side.
298  */
299 struct rpcap_openreply
300 {
301 	int32 linktype;	/* Link type */
302 	int32 tzoff;	/* Timezone offset */
303 };
304 
305 /* Format of the message that starts a remote capture (startcap command) */
306 struct rpcap_startcapreq
307 {
308 	uint32 snaplen;		/* Length of the snapshot (number of bytes to capture for each packet) */
309 	uint32 read_timeout;	/* Read timeout in milliseconds */
310 	uint16 flags;		/* Flags (see RPCAP_STARTCAPREQ_FLAG_xxx) */
311 	uint16 portdata;	/* Network port on which the client is waiting at (if 'serveropen') */
312 };
313 
314 /* Format of the reply message that devoted to start a remote capture (startcap reply command) */
315 struct rpcap_startcapreply
316 {
317 	int32 bufsize;		/* Size of the user buffer allocated by WinPcap; it can be different from the one we chose */
318 	uint16 portdata;	/* Network port on which the server is waiting at (passive mode only) */
319 	uint16 dummy;		/* Must be zero */
320 };
321 
322 /*
323  * \brief Format of the header which encapsulates captured packets when transmitted on the network.
324  *
325  * This message requires the general header as well, since we want to be able to exchange
326  * more information across the network in the future (for example statistics, and kind like that).
327  */
328 struct rpcap_pkthdr
329 {
330 	uint32 timestamp_sec;	/* 'struct timeval' compatible, it represents the 'tv_sec' field */
331 	uint32 timestamp_usec;	/* 'struct timeval' compatible, it represents the 'tv_usec' field */
332 	uint32 caplen;		/* Length of portion present in the capture */
333 	uint32 len;		/* Real length this packet (off wire) */
334 	uint32 npkt;		/* Ordinal number of the packet (i.e. the first one captured has '1', the second one '2', etc) */
335 };
336 
337 /* General header used for the pcap_setfilter() command; keeps just the number of BPF instructions */
338 struct rpcap_filter
339 {
340 	uint16 filtertype;	/* type of the filter transferred (BPF instructions, ...) */
341 	uint16 dummy;		/* Must be zero */
342 	uint32 nitems;		/* Number of items contained into the filter (e.g. BPF instructions for BPF filters) */
343 };
344 
345 /* Structure that keeps a single BPF instuction; it is repeated 'ninsn' times according to the 'rpcap_filterbpf' header */
346 struct rpcap_filterbpf_insn
347 {
348 	uint16 code;	/* opcode of the instruction */
349 	uint8 jt;	/* relative offset to jump to in case of 'true' */
350 	uint8 jf;	/* relative offset to jump to in case of 'false' */
351 	int32 k;	/* instruction-dependent value */
352 };
353 
354 /* Structure that keeps the data required for the authentication on the remote host */
355 struct rpcap_auth
356 {
357 	uint16 type;	/* Authentication type */
358 	uint16 dummy;	/* Must be zero */
359 	uint16 slen1;	/* Length of the first authentication item (e.g. username) */
360 	uint16 slen2;	/* Length of the second authentication item (e.g. password) */
361 };
362 
363 /* Structure that keeps the statistics about the number of packets captured, dropped, etc. */
364 struct rpcap_stats
365 {
366 	uint32 ifrecv;		/* Packets received by the kernel filter (i.e. pcap_stats.ps_recv) */
367 	uint32 ifdrop;		/* Packets dropped by the network interface (e.g. not enough buffers) (i.e. pcap_stats.ps_ifdrop) */
368 	uint32 krnldrop;	/* Packets dropped by the kernel filter (i.e. pcap_stats.ps_drop) */
369 	uint32 svrcapt;		/* Packets captured by the RPCAP daemon and sent on the network */
370 };
371 
372 /* Structure that is needed to set sampling parameters */
373 struct rpcap_sampling
374 {
375 	uint8 method;	/* Sampling method */
376 	uint8 dummy1;	/* Must be zero */
377 	uint16 dummy2;	/* Must be zero */
378 	uint32 value;	/* Parameter related to the sampling method */
379 };
380 
381 /* Messages field coding */
382 #define RPCAP_MSG_IS_REPLY		0x080	/* Flag indicating a reply */
383 
384 #define RPCAP_MSG_ERROR			1	/* Message that keeps an error notification */
385 #define RPCAP_MSG_FINDALLIF_REQ		2	/* Request to list all the remote interfaces */
386 #define RPCAP_MSG_OPEN_REQ		3	/* Request to open a remote device */
387 #define RPCAP_MSG_STARTCAP_REQ		4	/* Request to start a capture on a remote device */
388 #define RPCAP_MSG_UPDATEFILTER_REQ	5	/* Send a compiled filter into the remote device */
389 #define RPCAP_MSG_CLOSE			6	/* Close the connection with the remote peer */
390 #define RPCAP_MSG_PACKET		7	/* This is a 'data' message, which carries a network packet */
391 #define RPCAP_MSG_AUTH_REQ		8	/* Message that keeps the authentication parameters */
392 #define RPCAP_MSG_STATS_REQ		9	/* It requires to have network statistics */
393 #define RPCAP_MSG_ENDCAP_REQ		10	/* Stops the current capture, keeping the device open */
394 #define RPCAP_MSG_SETSAMPLING_REQ	11	/* Set sampling parameters */
395 
396 #define RPCAP_MSG_FINDALLIF_REPLY	(RPCAP_MSG_FINDALLIF_REQ | RPCAP_MSG_IS_REPLY)		/* Keeps the list of all the remote interfaces */
397 #define RPCAP_MSG_OPEN_REPLY		(RPCAP_MSG_OPEN_REQ | RPCAP_MSG_IS_REPLY)		/* The remote device has been opened correctly */
398 #define RPCAP_MSG_STARTCAP_REPLY	(RPCAP_MSG_STARTCAP_REQ | RPCAP_MSG_IS_REPLY)		/* The capture is starting correctly */
399 #define RPCAP_MSG_UPDATEFILTER_REPLY	(RPCAP_MSG_UPDATEFILTER_REQ | RPCAP_MSG_IS_REPLY)	/* The filter has been applied correctly on the remote device */
400 #define RPCAP_MSG_AUTH_REPLY		(RPCAP_MSG_AUTH_REQ | RPCAP_MSG_IS_REPLY)		/* Sends a message that says 'ok, authorization successful' */
401 #define RPCAP_MSG_STATS_REPLY		(RPCAP_MSG_STATS_REQ | RPCAP_MSG_IS_REPLY)		/* Message that keeps the network statistics */
402 #define RPCAP_MSG_ENDCAP_REPLY		(RPCAP_MSG_ENDCAP_REQ | RPCAP_MSG_IS_REPLY)		/* Confirms that the capture stopped successfully */
403 #define RPCAP_MSG_SETSAMPLING_REPLY	(RPCAP_MSG_SETSAMPLING_REQ | RPCAP_MSG_IS_REPLY)		/* Confirms that the capture stopped successfully */
404 
405 #define RPCAP_STARTCAPREQ_FLAG_PROMISC		0x00000001	/* Enables promiscuous mode (default: disabled) */
406 #define RPCAP_STARTCAPREQ_FLAG_DGRAM		0x00000002	/* Use a datagram (i.e. UDP) connection for the data stream (default: use TCP)*/
407 #define RPCAP_STARTCAPREQ_FLAG_SERVEROPEN	0x00000004	/* The server has to open the data connection toward the client */
408 #define RPCAP_STARTCAPREQ_FLAG_INBOUND		0x00000008	/* Capture only inbound packets (take care: the flag has no effect with promiscuous enabled) */
409 #define RPCAP_STARTCAPREQ_FLAG_OUTBOUND		0x00000010	/* Capture only outbound packets (take care: the flag has no effect with promiscuous enabled) */
410 
411 #define RPCAP_UPDATEFILTER_BPF 1			/* This code tells us that the filter is encoded with the BPF/NPF syntax */
412 
413 /* Network error codes */
414 #define PCAP_ERR_NETW		1	/* Network error */
415 #define PCAP_ERR_INITTIMEOUT	2	/* The RPCAP initial timeout has expired */
416 #define PCAP_ERR_AUTH		3	/* Generic authentication error */
417 #define PCAP_ERR_FINDALLIF	4	/* Generic findalldevs error */
418 #define PCAP_ERR_NOREMOTEIF	5	/* The findalldevs was ok, but the remote end had no interfaces to list */
419 #define PCAP_ERR_OPEN		6	/* Generic pcap_open error */
420 #define PCAP_ERR_UPDATEFILTER	7	/* Generic updatefilter error */
421 #define PCAP_ERR_GETSTATS	8	/* Generic pcap_stats error */
422 #define PCAP_ERR_READEX		9	/* Generic pcap_next_ex error */
423 #define PCAP_ERR_HOSTNOAUTH	10	/* The host is not authorized to connect to this server */
424 #define PCAP_ERR_REMOTEACCEPT	11	/* Generic pcap_remoteaccept error */
425 #define PCAP_ERR_STARTCAPTURE	12	/* Generic pcap_startcapture error */
426 #define PCAP_ERR_ENDCAPTURE	13	/* Generic pcap_endcapture error */
427 #define PCAP_ERR_RUNTIMETIMEOUT	14	/* The RPCAP run-time timeout has expired */
428 #define PCAP_ERR_SETSAMPLING	15	/* Error during the settings of sampling parameters */
429 #define PCAP_ERR_WRONGMSG	16	/* The other end endpoint sent a message which has not been recognized */
430 #define PCAP_ERR_WRONGVER	17	/* The other end endpoint has a version number that is not compatible with our */
431 
432 /*
433  * \brief Buffer used by socket functions to send-receive packets.
434  * In case you plan to have messages larger than this value, you have to increase it.
435  */
436 #define RPCAP_NETBUF_SIZE 64000
437 
438 /*********************************************************
439  *                                                       *
440  * Routines used by the rpcap client and rpcap daemon    *
441  *                                                       *
442  *********************************************************/
443 
444 #include "sockutils.h"
445 
446 extern void rpcap_createhdr(struct rpcap_header *header, uint8 ver, uint8 type, uint16 value, uint32 length);
447 extern const char *rpcap_msg_type_string(uint8 type);
448 extern int rpcap_senderror(SOCKET sock, uint8 ver, uint16 errcode, const char *error, char *errbuf);
449 
450 #endif
451