libpcap  1.10.1
About: libpcap is a packet filter library used by tools like tcpdump.
  Fossies Dox: libpcap-1.10.1.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

rpcap-protocol.h
Go to the documentation of this file.
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 a version number
67  * of 0. All servers must accept authentication requests with a version
68  * number of 0, even if they don't support version 0 for any other
69  * requests.
70  *
71  * The server attempts to authenticate the client. If that succeeds,
72  * older servers - which only support version 0 - will send an
73  * authentication reply with no payload. Newer servers - which might
74  * support other versions - will send an authentication reply with
75  * a payload giving the minimum and maximum versions it supports.
76  *
77  * The client attempts to find the largest version number that is
78  * in both its range of supported versions and the server's supported
79  * versions. If it fails, it gives up; otherwise, it uses that version.
80  */
81 #define RPCAP_MIN_VERSION 0
82 #define RPCAP_MAX_VERSION 0
83 
84 /*
85  * Version numbers are unsigned, so if RPCAP_MIN_VERSION is 0, they
86  * are >= the minimum version, by definition; don't check against
87  * RPCAP_MIN_VERSION, as you may get compiler warnings that the
88  * comparison will always succeed.
89  */
90 #if RPCAP_MIN_VERSION == 0
91 #define RPCAP_VERSION_IS_SUPPORTED(v) \
92  ((v) <= RPCAP_MAX_VERSION)
93 #else
94 #define RPCAP_VERSION_IS_SUPPORTED(v) \
95  ((v) >= RPCAP_MIN_VERSION && (v) <= RPCAP_MAX_VERSION)
96 #endif
97 
98 /*
99  * Separators used for the host list.
100  *
101  * It is used:
102  * - by the rpcapd daemon, when you types a list of allowed connecting hosts
103  * - by the rpcap client in active mode, when the client waits for incoming
104  * connections from other hosts
105  */
106 #define RPCAP_HOSTLIST_SEP " ,;\n\r"
107 
108 /*********************************************************
109  * *
110  * Protocol messages formats *
111  * *
112  *********************************************************/
113 /*
114  * WARNING: This file defines some structures that are used to transfer
115  * data on the network.
116  * Note that your compiler MUST not insert padding into these structures
117  * for better alignment.
118  * These structures have been created in order to be correctly aligned to
119  * a 32-bit boundary, but be careful in any case.
120  *
121  * The layout of these structures MUST not be changed. If a packet
122  * format is different in different versions of the protocol, versions
123  * of the structure should be provided for all the different versions or
124  * version ranges (if more than one version of the protocol has the same
125  * layout) that we support.
126  */
127 
128 /*
129  * WARNING: These typedefs MUST be of a specific size.
130  * You might have to change them on your platform.
131  *
132  * XXX - use the C99 types? Microsoft's newer versions of Visual Studio
133  * support them.
134  */
135 typedef unsigned char uint8; /* 8-bit unsigned integer */
136 typedef unsigned short uint16; /* 16-bit unsigned integer */
137 typedef unsigned int uint32; /* 32-bit unsigned integer */
138 typedef int int32; /* 32-bit signed integer */
139 
140 /* Common header for all the RPCAP messages */
142 {
143  uint8 ver; /* RPCAP version number */
144  uint8 type; /* RPCAP message type (error, findalldevs, ...) */
145  uint16 value; /* Message-dependent value (not always used) */
146  uint32 plen; /* Length of the payload of this RPCAP message */
147 };
148 
149 /*
150  * Format of data that may appear at the end of an authentication reply,
151  * giving the minimum and maximum versions of the protocol that the
152  * server supports.
153  *
154  * Older servers don't provide this; they support only version 0.
155  */
157 {
158  uint8 minvers; /* Minimum version supported */
159  uint8 maxvers; /* Maximum version supported */
160 };
161 
162 /* Format of the message for the interface description (findalldevs command) */
164 {
165  uint16 namelen; /* Length of the interface name */
166  uint16 desclen; /* Length of the interface description */
167  uint32 flags; /* Interface flags */
168  uint16 naddr; /* Number of addresses */
169  uint16 dummy; /* Must be zero */
170 };
171 
172 /*
173  * Format of an address as sent over the wire.
174  *
175  * Do *NOT* use struct sockaddr_storage, as the layout for that is
176  * machine-dependent.
177  *
178  * RFC 2553 gives two sample layouts, both of which are 128 bytes long,
179  * both of which are aligned on an 8-byte boundary, and both of which
180  * have 2 bytes before the address data.
181  *
182  * However, one has a 2-byte address family value at the beginning
183  * and the other has a 1-byte address length value and a 1-byte
184  * address family value; this reflects the fact that the original
185  * BSD sockaddr structure had a 2-byte address family value, which
186  * was later changed to a 1-byte address length value and a 1-byte
187  * address family value, when support for variable-length OSI
188  * network-layer addresses was added.
189  *
190  * Furthermore, Solaris's struct sockaddr_storage is 256 bytes
191  * long.
192  *
193  * This structure is supposed to be aligned on an 8-byte boundary;
194  * the message header is 8 bytes long, so we don't have to do
195  * anything to ensure it's aligned on that boundary within a packet,
196  * so we just define it as 128 bytes long, with a 2-byte address
197  * family. (We only support IPv4 and IPv6 addresses, which are fixed-
198  * length.) That way, it's the same size as sockaddr_storage on
199  * Windows, and it'll look like what an older Windows client will
200  * expect.
201  *
202  * In addition, do *NOT* use the host's AF_ value for an address,
203  * as the value for AF_INET6 is machine-dependent. We use the
204  * Windows value, so it'll look like what an older Windows client
205  * will expect.
206  *
207  * (The Windows client is the only one that has been distributed
208  * as a standard part of *pcap; UN*X clients are probably built
209  * from source by the user or administrator, so they're in a
210  * better position to upgrade an old client. Therefore, we
211  * try to make what goes over the wire look like what comes
212  * from a Windows server.)
213  */
215 {
216  uint16 family; /* Address family */
217  char data[128-2]; /* Data */
218 };
219 
220 /*
221  * Format of an IPv4 address as sent over the wire.
222  */
223 #define RPCAP_AF_INET 2 /* Value on all OSes */
225 {
226  uint16 family; /* Address family */
227  uint16 port; /* Port number */
228  uint32 addr; /* IPv4 address */
229  uint8 zero[8]; /* Padding */
230 };
231 
232 /*
233  * Format of an IPv6 address as sent over the wire.
234  */
235 #define RPCAP_AF_INET6 23 /* Value on Windows */
237 {
238  uint16 family; /* Address family */
239  uint16 port; /* Port number */
240  uint32 flowinfo; /* IPv6 flow information */
241  uint8 addr[16]; /* IPv6 address */
242  uint32 scope_id; /* Scope zone index */
243 };
244 
245 /* Format of the message for the address listing (findalldevs command) */
247 {
248  struct rpcap_sockaddr addr; /* Network address */
249  struct rpcap_sockaddr netmask; /* Netmask for that address */
250  struct rpcap_sockaddr broadaddr; /* Broadcast address for that address */
251  struct rpcap_sockaddr dstaddr; /* P2P destination address for that address */
252 };
253 
254 /*
255  * \brief Format of the message of the connection opening reply (open command).
256  *
257  * This structure transfers over the network some of the values useful on the client side.
258  */
260 {
261  int32 linktype; /* Link type */
262  int32 tzoff; /* Timezone offset - not used by newer clients */
263 };
264 
265 /* Format of the message that starts a remote capture (startcap command) */
267 {
268  uint32 snaplen; /* Length of the snapshot (number of bytes to capture for each packet) */
269  uint32 read_timeout; /* Read timeout in milliseconds */
270  uint16 flags; /* Flags (see RPCAP_STARTCAPREQ_FLAG_xxx) */
271  uint16 portdata; /* Network port on which the client is waiting at (if 'serveropen') */
272 };
273 
274 /* Format of the reply message that devoted to start a remote capture (startcap reply command) */
276 {
277  int32 bufsize; /* Size of the user buffer allocated by WinPcap; it can be different from the one we chose */
278  uint16 portdata; /* Network port on which the server is waiting at (passive mode only) */
279  uint16 dummy; /* Must be zero */
280 };
281 
282 /*
283  * \brief Format of the header which encapsulates captured packets when transmitted on the network.
284  *
285  * This message requires the general header as well, since we want to be able to exchange
286  * more information across the network in the future (for example statistics, and kind like that).
287  */
289 {
290  /*
291  * This protocol needs to be updated with a new version before
292  * 2038-01-19 03:14:07 UTC.
293  */
294  uint32 timestamp_sec; /* 'struct timeval' compatible, it represents the 'tv_sec' field */
295  uint32 timestamp_usec; /* 'struct timeval' compatible, it represents the 'tv_usec' field */
296  uint32 caplen; /* Length of portion present in the capture */
297  uint32 len; /* Real length of this packet (off wire) */
298  uint32 npkt; /* Ordinal number of the packet (i.e. the first one captured has '1', the second one '2', etc) */
299 };
300 
301 /* General header used for the pcap_setfilter() command; keeps just the number of BPF instructions */
303 {
304  uint16 filtertype; /* type of the filter transferred (BPF instructions, ...) */
305  uint16 dummy; /* Must be zero */
306  uint32 nitems; /* Number of items contained into the filter (e.g. BPF instructions for BPF filters) */
307 };
308 
309 /* Structure that keeps a single BPF instruction; it is repeated 'ninsn' times according to the 'rpcap_filterbpf' header */
311 {
312  uint16 code; /* opcode of the instruction */
313  uint8 jt; /* relative offset to jump to in case of 'true' */
314  uint8 jf; /* relative offset to jump to in case of 'false' */
315  int32 k; /* instruction-dependent value */
316 };
317 
318 /* Structure that keeps the data required for the authentication on the remote host */
320 {
321  uint16 type; /* Authentication type */
322  uint16 dummy; /* Must be zero */
323  uint16 slen1; /* Length of the first authentication item (e.g. username) */
324  uint16 slen2; /* Length of the second authentication item (e.g. password) */
325 };
326 
327 /* Structure that keeps the statistics about the number of packets captured, dropped, etc. */
329 {
330  uint32 ifrecv; /* Packets received by the kernel filter (i.e. pcap_stats.ps_recv) */
331  uint32 ifdrop; /* Packets dropped by the network interface (e.g. not enough buffers) (i.e. pcap_stats.ps_ifdrop) */
332  uint32 krnldrop; /* Packets dropped by the kernel filter (i.e. pcap_stats.ps_drop) */
333  uint32 svrcapt; /* Packets captured by the RPCAP daemon and sent on the network */
334 };
335 
336 /* Structure that is needed to set sampling parameters */
338 {
339  uint8 method; /* Sampling method */
340  uint8 dummy1; /* Must be zero */
341  uint16 dummy2; /* Must be zero */
342  uint32 value; /* Parameter related to the sampling method */
343 };
344 
345 /*
346  * Messages field coding.
347  *
348  * These values are used in messages sent over the network, and MUST
349  * not be changed.
350  */
351 #define RPCAP_MSG_IS_REPLY 0x080 /* Flag indicating a reply */
352 
353 #define RPCAP_MSG_ERROR 0x01 /* Message that keeps an error notification */
354 #define RPCAP_MSG_FINDALLIF_REQ 0x02 /* Request to list all the remote interfaces */
355 #define RPCAP_MSG_OPEN_REQ 0x03 /* Request to open a remote device */
356 #define RPCAP_MSG_STARTCAP_REQ 0x04 /* Request to start a capture on a remote device */
357 #define RPCAP_MSG_UPDATEFILTER_REQ 0x05 /* Send a compiled filter into the remote device */
358 #define RPCAP_MSG_CLOSE 0x06 /* Close the connection with the remote peer */
359 #define RPCAP_MSG_PACKET 0x07 /* This is a 'data' message, which carries a network packet */
360 #define RPCAP_MSG_AUTH_REQ 0x08 /* Message that keeps the authentication parameters */
361 #define RPCAP_MSG_STATS_REQ 0x09 /* It requires to have network statistics */
362 #define RPCAP_MSG_ENDCAP_REQ 0x0A /* Stops the current capture, keeping the device open */
363 #define RPCAP_MSG_SETSAMPLING_REQ 0x0B /* Set sampling parameters */
364 
365 #define RPCAP_MSG_FINDALLIF_REPLY (RPCAP_MSG_FINDALLIF_REQ | RPCAP_MSG_IS_REPLY) /* Keeps the list of all the remote interfaces */
366 #define RPCAP_MSG_OPEN_REPLY (RPCAP_MSG_OPEN_REQ | RPCAP_MSG_IS_REPLY) /* The remote device has been opened correctly */
367 #define RPCAP_MSG_STARTCAP_REPLY (RPCAP_MSG_STARTCAP_REQ | RPCAP_MSG_IS_REPLY) /* The capture is starting correctly */
368 #define RPCAP_MSG_UPDATEFILTER_REPLY (RPCAP_MSG_UPDATEFILTER_REQ | RPCAP_MSG_IS_REPLY) /* The filter has been applied correctly on the remote device */
369 #define RPCAP_MSG_AUTH_REPLY (RPCAP_MSG_AUTH_REQ | RPCAP_MSG_IS_REPLY) /* Sends a message that says 'ok, authorization successful' */
370 #define RPCAP_MSG_STATS_REPLY (RPCAP_MSG_STATS_REQ | RPCAP_MSG_IS_REPLY) /* Message that keeps the network statistics */
371 #define RPCAP_MSG_ENDCAP_REPLY (RPCAP_MSG_ENDCAP_REQ | RPCAP_MSG_IS_REPLY) /* Confirms that the capture stopped successfully */
372 #define RPCAP_MSG_SETSAMPLING_REPLY (RPCAP_MSG_SETSAMPLING_REQ | RPCAP_MSG_IS_REPLY) /* Confirms that the capture stopped successfully */
373 
374 #define RPCAP_STARTCAPREQ_FLAG_PROMISC 0x00000001 /* Enables promiscuous mode (default: disabled) */
375 #define RPCAP_STARTCAPREQ_FLAG_DGRAM 0x00000002 /* Use a datagram (i.e. UDP) connection for the data stream (default: use TCP)*/
376 #define RPCAP_STARTCAPREQ_FLAG_SERVEROPEN 0x00000004 /* The server has to open the data connection toward the client */
377 #define RPCAP_STARTCAPREQ_FLAG_INBOUND 0x00000008 /* Capture only inbound packets (take care: the flag has no effect with promiscuous enabled) */
378 #define RPCAP_STARTCAPREQ_FLAG_OUTBOUND 0x00000010 /* Capture only outbound packets (take care: the flag has no effect with promiscuous enabled) */
379 
380 #define RPCAP_UPDATEFILTER_BPF 1 /* This code tells us that the filter is encoded with the BPF/NPF syntax */
381 
382 /*
383  * Network error codes.
384  *
385  * These values are used in messages sent over the network, and MUST
386  * not be changed.
387  */
388 #define PCAP_ERR_NETW 1 /* Network error */
389 #define PCAP_ERR_INITTIMEOUT 2 /* The RPCAP initial timeout has expired */
390 #define PCAP_ERR_AUTH 3 /* Generic authentication error */
391 #define PCAP_ERR_FINDALLIF 4 /* Generic findalldevs error */
392 #define PCAP_ERR_NOREMOTEIF 5 /* The findalldevs was ok, but the remote end had no interfaces to list */
393 #define PCAP_ERR_OPEN 6 /* Generic pcap_open error */
394 #define PCAP_ERR_UPDATEFILTER 7 /* Generic updatefilter error */
395 #define PCAP_ERR_GETSTATS 8 /* Generic pcap_stats error */
396 #define PCAP_ERR_READEX 9 /* Generic pcap_next_ex error */
397 #define PCAP_ERR_HOSTNOAUTH 10 /* The host is not authorized to connect to this server */
398 #define PCAP_ERR_REMOTEACCEPT 11 /* Generic pcap_remoteaccept error */
399 #define PCAP_ERR_STARTCAPTURE 12 /* Generic pcap_startcapture error */
400 #define PCAP_ERR_ENDCAPTURE 13 /* Generic pcap_endcapture error */
401 #define PCAP_ERR_RUNTIMETIMEOUT 14 /* The RPCAP run-time timeout has expired */
402 #define PCAP_ERR_SETSAMPLING 15 /* Error during the settings of sampling parameters */
403 #define PCAP_ERR_WRONGMSG 16 /* The other end endpoint sent a message which has not been recognized */
404 #define PCAP_ERR_WRONGVER 17 /* The other end endpoint has a version number that is not compatible with our */
405 #define PCAP_ERR_AUTH_FAILED 18 /* The user couldn't be authenticated */
406 #define PCAP_ERR_TLS_REQUIRED 19 /* The server requires TLS to connect */
407 #define PCAP_ERR_AUTH_TYPE_NOTSUP 20 /* The authentication type isn't supported */
408 
409 /*
410  * \brief Buffer used by socket functions to send-receive packets.
411  * In case you plan to have messages larger than this value, you have to increase it.
412  */
413 #define RPCAP_NETBUF_SIZE 64000
414 
415 /*********************************************************
416  * *
417  * Routines used by the rpcap client and rpcap daemon *
418  * *
419  *********************************************************/
420 
421 #include "sockutils.h"
422 #include "sslutils.h"
423 
424 extern void rpcap_createhdr(struct rpcap_header *header, uint8 ver, uint8 type, uint16 value, uint32 length);
425 extern const char *rpcap_msg_type_string(uint8 type);
426 extern int rpcap_senderror(SOCKET sock, SSL *ssl, uint8 ver, uint16 errcode, const char *error, char *errbuf);
427 
428 #endif
static void error(const char *,...)
unsigned short uint16
const char * rpcap_msg_type_string(uint8 type)
unsigned int uint32
int int32
void rpcap_createhdr(struct rpcap_header *header, uint8 ver, uint8 type, uint16 value, uint32 length)
unsigned char uint8
int rpcap_senderror(int sock, void const *ssl, uint8 ver, uint16 errcode, const char *error, char *errbuf)
#define SOCKET
In Winsock, a socket handle is of type SOCKET; in UN*X, it's a file descriptor, and therefore a signe...
Definition: socket.h:70
#define SSL
Definition: sslutils.h:59
struct rpcap_sockaddr netmask
struct rpcap_sockaddr broadaddr
struct rpcap_sockaddr addr
struct rpcap_sockaddr dstaddr
uint32 timestamp_usec
uint32 timestamp_sec
char data[128-2]