rpcap-protocol.h

   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