contrib/libpcap/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 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 #ifndef __HAIKU__
 136 typedef unsigned char uint8;    /* 8-bit unsigned integer */
 137 typedef unsigned short uint16;  /* 16-bit unsigned integer */
 138 typedef unsigned int uint32;    /* 32-bit unsigned integer */
 139 typedef int int32;              /* 32-bit signed integer */
 140 #endif
 141
 142 /* Common header for all the RPCAP messages */
 143 struct rpcap_header
 144 {
 145         uint8 ver;      /* RPCAP version number */
 146         uint8 type;     /* RPCAP message type (error, findalldevs, ...) */
 147         uint16 value;   /* Message-dependent value (not always used) */
 148         uint32 plen;    /* Length of the payload of this RPCAP message */
 149 };
 150
 151 /*
 152  * Format of data that may appear at the end of an authentication reply,
 153  * giving the minimum and maximum versions of the protocol that the
 154  * server supports.
 155  *
 156  * Older servers don't provide this; they support only version 0.
 157  */
 158 struct rpcap_authreply
 159 {
 160         uint8 minvers;                  /* Minimum version supported */
 161         uint8 maxvers;                  /* Maximum version supported */
 162         uint8 pad[2];                   /* Pad to 4-byte boundary **/
 163         uint32 byte_order_magic;        /* RPCAP_BYTE_ORDER_MAGIC, in server byte order */
 164 };
 165
 166 /*
 167  * Any resemblance between this and the pcap file magic number
 168  * is purely coincidental, trust me.
 169  */
 170 #define RPCAP_BYTE_ORDER_MAGIC          0xa1b2c3d4U
 171 #define RPCAP_BYTE_ORDER_MAGIC_SWAPPED  0xd4c3b2a1U
 172
 173 /*
 174  * Older version of authentication reply, without byte order indication
 175  * and padding.
 176  */
 177 struct rpcap_authreply_old
 178 {
 179         uint8 minvers;  /* Minimum version supported */
 180         uint8 maxvers;  /* Maximum version supported */
 181 };
 182
 183 /* Format of the message for the interface description (findalldevs command) */
 184 struct rpcap_findalldevs_if
 185 {
 186         uint16 namelen; /* Length of the interface name */
 187         uint16 desclen; /* Length of the interface description */
 188         uint32 flags;   /* Interface flags */
 189         uint16 naddr;   /* Number of addresses */
 190         uint16 dummy;   /* Must be zero */
 191 };
 192
 193 /*
 194  * Format of an address as sent over the wire.
 195  *
 196  * Do *NOT* use struct sockaddr_storage, as the layout for that is
 197  * machine-dependent.
 198  *
 199  * RFC 2553 gives two sample layouts, both of which are 128 bytes long,
 200  * both of which are aligned on an 8-byte boundary, and both of which
 201  * have 2 bytes before the address data.
 202  *
 203  * However, one has a 2-byte address family value at the beginning
 204  * and the other has a 1-byte address length value and a 1-byte
 205  * address family value; this reflects the fact that the original
 206  * BSD sockaddr structure had a 2-byte address family value, which
 207  * was later changed to a 1-byte address length value and a 1-byte
 208  * address family value, when support for variable-length OSI
 209  * network-layer addresses was added.
 210  *
 211  * Furthermore, Solaris's struct sockaddr_storage is 256 bytes
 212  * long.
 213  *
 214  * This structure is supposed to be aligned on an 8-byte boundary;
 215  * the message header is 8 bytes long, so we don't have to do
 216  * anything to ensure it's aligned on that boundary within a packet,
 217  * so we just define it as 128 bytes long, with a 2-byte address
 218  * family.  (We only support IPv4 and IPv6 addresses, which are fixed-
 219  * length.)  That way, it's the same size as sockaddr_storage on
 220  * Windows, and it'll look like what an older Windows client will
 221  * expect.
 222  *
 223  * In addition, do *NOT* use the host's AF_ value for an address,
 224  * as the value for AF_INET6 is machine-dependent.  We use the
 225  * Windows value, so it'll look like what an older Windows client
 226  * will expect.
 227  *
 228  * (The Windows client is the only one that has been distributed
 229  * as a standard part of *pcap; UN*X clients are probably built
 230  * from source by the user or administrator, so they're in a
 231  * better position to upgrade an old client.  Therefore, we
 232  * try to make what goes over the wire look like what comes
 233  * from a Windows server.)
 234  */
 235 struct rpcap_sockaddr
 236 {
 237         uint16  family;                 /* Address family */
 238         char    data[128-2];            /* Data */
 239 };
 240
 241 /*
 242  * Format of an IPv4 address as sent over the wire.
 243  */
 244 #define RPCAP_AF_INET   2               /* Value on all OSes */
 245 struct rpcap_sockaddr_in
 246 {
 247         uint16  family;                 /* Address family */
 248         uint16  port;                   /* Port number */
 249         uint32  addr;                   /* IPv4 address */
 250         uint8   zero[8];                /* Padding */
 251 };
 252
 253 /*
 254  * Format of an IPv6 address as sent over the wire.
 255  */
 256 #define RPCAP_AF_INET6  23              /* Value on Windows */
 257 struct rpcap_sockaddr_in6
 258 {
 259         uint16  family;                 /* Address family */
 260         uint16  port;                   /* Port number */
 261         uint32  flowinfo;               /* IPv6 flow information */
 262         uint8   addr[16];               /* IPv6 address */
 263         uint32  scope_id;               /* Scope zone index */
 264 };
 265
 266 /* Format of the message for the address listing (findalldevs command) */
 267 struct rpcap_findalldevs_ifaddr
 268 {
 269         struct rpcap_sockaddr addr;             /* Network address */
 270         struct rpcap_sockaddr netmask;          /* Netmask for that address */
 271         struct rpcap_sockaddr broadaddr;        /* Broadcast address for that address */
 272         struct rpcap_sockaddr dstaddr;          /* P2P destination address for that address */
 273 };
 274
 275 /*
 276  * \brief Format of the message of the connection opening reply (open command).
 277  *
 278  * This structure transfers over the network some of the values useful on the client side.
 279  */
 280 struct rpcap_openreply
 281 {
 282         int32 linktype; /* Link type */
 283         int32 tzoff;    /* Timezone offset - not used by newer clients */
 284 };
 285
 286 /* Format of the message that starts a remote capture (startcap command) */
 287 struct rpcap_startcapreq
 288 {
 289         uint32 snaplen;         /* Length of the snapshot (number of bytes to capture for each packet) */
 290         uint32 read_timeout;    /* Read timeout in milliseconds */
 291         uint16 flags;           /* Flags (see RPCAP_STARTCAPREQ_FLAG_xxx) */
 292         uint16 portdata;        /* Network port on which the client is waiting at (if 'serveropen') */
 293 };
 294
 295 /* Format of the reply message that devoted to start a remote capture (startcap reply command) */
 296 struct rpcap_startcapreply
 297 {
 298         int32 bufsize;          /* Size of the user buffer allocated by WinPcap; it can be different from the one we chose */
 299         uint16 portdata;        /* Network port on which the server is waiting at (passive mode only) */
 300         uint16 dummy;           /* Must be zero */
 301 };
 302
 303 /*
 304  * \brief Format of the header which encapsulates captured packets when transmitted on the network.
 305  *
 306  * This message requires the general header as well, since we want to be able to exchange
 307  * more information across the network in the future (for example statistics, and kind like that).
 308  */
 309 struct rpcap_pkthdr
 310 {
 311         /*
 312          * This protocol needs to be updated with a new version before
 313          * 2038-01-19 03:14:07 UTC.
 314          */
 315         uint32 timestamp_sec;   /* 'struct timeval' compatible, it represents the 'tv_sec' field */
 316         uint32 timestamp_usec;  /* 'struct timeval' compatible, it represents the 'tv_usec' field */
 317         uint32 caplen;          /* Length of portion present in the capture */
 318         uint32 len;             /* Real length of this packet (off wire) */
 319         uint32 npkt;            /* Ordinal number of the packet (i.e. the first one captured has '1', the second one '2', etc) */
 320 };
 321
 322 /* General header used for the pcap_setfilter() command; keeps just the number of BPF instructions */
 323 struct rpcap_filter
 324 {
 325         uint16 filtertype;      /* type of the filter transferred (BPF instructions, ...) */
 326         uint16 dummy;           /* Must be zero */
 327         uint32 nitems;          /* Number of items contained into the filter (e.g. BPF instructions for BPF filters) */
 328 };
 329
 330 /* Structure that keeps a single BPF instruction; it is repeated 'ninsn' times according to the 'rpcap_filterbpf' header */
 331 struct rpcap_filterbpf_insn
 332 {
 333         uint16 code;    /* opcode of the instruction */
 334         uint8 jt;       /* relative offset to jump to in case of 'true' */
 335         uint8 jf;       /* relative offset to jump to in case of 'false' */
 336         int32 k;        /* instruction-dependent value */
 337 };
 338
 339 /* Structure that keeps the data required for the authentication on the remote host */
 340 struct rpcap_auth
 341 {
 342         uint16 type;    /* Authentication type */
 343         uint16 dummy;   /* Must be zero */
 344         uint16 slen1;   /* Length of the first authentication item (e.g. username) */
 345         uint16 slen2;   /* Length of the second authentication item (e.g. password) */
 346 };
 347
 348 /* Structure that keeps the statistics about the number of packets captured, dropped, etc. */
 349 struct rpcap_stats
 350 {
 351         uint32 ifrecv;          /* Packets received by the kernel filter (i.e. pcap_stats.ps_recv) */
 352         uint32 ifdrop;          /* Packets dropped by the network interface (e.g. not enough buffers) (i.e. pcap_stats.ps_ifdrop) */
 353         uint32 krnldrop;        /* Packets dropped by the kernel filter (i.e. pcap_stats.ps_drop) */
 354         uint32 svrcapt;         /* Packets captured by the RPCAP daemon and sent on the network */
 355 };
 356
 357 /* Structure that is needed to set sampling parameters */
 358 struct rpcap_sampling
 359 {
 360         uint8 method;   /* Sampling method */
 361         uint8 dummy1;   /* Must be zero */
 362         uint16 dummy2;  /* Must be zero */
 363         uint32 value;   /* Parameter related to the sampling method */
 364 };
 365
 366 /*
 367  * Messages field coding.
 368  *
 369  * These values are used in messages sent over the network, and MUST
 370  * not be changed.
 371  */
 372 #define RPCAP_MSG_IS_REPLY              0x080   /* Flag indicating a reply */
 373
 374 #define RPCAP_MSG_ERROR                 0x01    /* Message that keeps an error notification */
 375 #define RPCAP_MSG_FINDALLIF_REQ         0x02    /* Request to list all the remote interfaces */
 376 #define RPCAP_MSG_OPEN_REQ              0x03    /* Request to open a remote device */
 377 #define RPCAP_MSG_STARTCAP_REQ          0x04    /* Request to start a capture on a remote device */
 378 #define RPCAP_MSG_UPDATEFILTER_REQ      0x05    /* Send a compiled filter into the remote device */
 379 #define RPCAP_MSG_CLOSE                 0x06    /* Close the connection with the remote peer */
 380 #define RPCAP_MSG_PACKET                0x07    /* This is a 'data' message, which carries a network packet */
 381 #define RPCAP_MSG_AUTH_REQ              0x08    /* Message that keeps the authentication parameters */
 382 #define RPCAP_MSG_STATS_REQ             0x09    /* It requires to have network statistics */
 383 #define RPCAP_MSG_ENDCAP_REQ            0x0A    /* Stops the current capture, keeping the device open */
 384 #define RPCAP_MSG_SETSAMPLING_REQ       0x0B    /* Set sampling parameters */
 385
 386 #define RPCAP_MSG_FINDALLIF_REPLY       (RPCAP_MSG_FINDALLIF_REQ | RPCAP_MSG_IS_REPLY)          /* Keeps the list of all the remote interfaces */
 387 #define RPCAP_MSG_OPEN_REPLY            (RPCAP_MSG_OPEN_REQ | RPCAP_MSG_IS_REPLY)               /* The remote device has been opened correctly */
 388 #define RPCAP_MSG_STARTCAP_REPLY        (RPCAP_MSG_STARTCAP_REQ | RPCAP_MSG_IS_REPLY)           /* The capture is starting correctly */
 389 #define RPCAP_MSG_UPDATEFILTER_REPLY    (RPCAP_MSG_UPDATEFILTER_REQ | RPCAP_MSG_IS_REPLY)       /* The filter has been applied correctly on the remote device */
 390 #define RPCAP_MSG_AUTH_REPLY            (RPCAP_MSG_AUTH_REQ | RPCAP_MSG_IS_REPLY)               /* Sends a message that says 'ok, authorization successful' */
 391 #define RPCAP_MSG_STATS_REPLY           (RPCAP_MSG_STATS_REQ | RPCAP_MSG_IS_REPLY)              /* Message that keeps the network statistics */
 392 #define RPCAP_MSG_ENDCAP_REPLY          (RPCAP_MSG_ENDCAP_REQ | RPCAP_MSG_IS_REPLY)             /* Confirms that the capture stopped successfully */
 393 #define RPCAP_MSG_SETSAMPLING_REPLY     (RPCAP_MSG_SETSAMPLING_REQ | RPCAP_MSG_IS_REPLY)                /* Confirms that the capture stopped successfully */
 394
 395 #define RPCAP_STARTCAPREQ_FLAG_PROMISC          0x00000001      /* Enables promiscuous mode (default: disabled) */
 396 #define RPCAP_STARTCAPREQ_FLAG_DGRAM            0x00000002      /* Use a datagram (i.e. UDP) connection for the data stream (default: use TCP)*/
 397 #define RPCAP_STARTCAPREQ_FLAG_SERVEROPEN       0x00000004      /* The server has to open the data connection toward the client */
 398 #define RPCAP_STARTCAPREQ_FLAG_INBOUND          0x00000008      /* Capture only inbound packets (take care: the flag has no effect with promiscuous enabled) */
 399 #define RPCAP_STARTCAPREQ_FLAG_OUTBOUND         0x00000010      /* Capture only outbound packets (take care: the flag has no effect with promiscuous enabled) */
 400
 401 #define RPCAP_UPDATEFILTER_BPF 1                        /* This code tells us that the filter is encoded with the BPF/NPF syntax */
 402
 403 /*
 404  * Network error codes.
 405  *
 406  * These values are used in messages sent over the network, and MUST
 407  * not be changed.
 408  */
 409 #define PCAP_ERR_NETW                   1       /* Network error */
 410 #define PCAP_ERR_INITTIMEOUT            2       /* The RPCAP initial timeout has expired */
 411 #define PCAP_ERR_AUTH                   3       /* Generic authentication error */
 412 #define PCAP_ERR_FINDALLIF              4       /* Generic findalldevs error */
 413 #define PCAP_ERR_NOREMOTEIF             5       /* The findalldevs was ok, but the remote end had no interfaces to list */
 414 #define PCAP_ERR_OPEN                   6       /* Generic pcap_open error */
 415 #define PCAP_ERR_UPDATEFILTER           7       /* Generic updatefilter error */
 416 #define PCAP_ERR_GETSTATS               8       /* Generic pcap_stats error */
 417 #define PCAP_ERR_READEX                 9       /* Generic pcap_next_ex error */
 418 #define PCAP_ERR_HOSTNOAUTH             10      /* The host is not authorized to connect to this server */
 419 #define PCAP_ERR_REMOTEACCEPT           11      /* Generic pcap_remoteaccept error */
 420 #define PCAP_ERR_STARTCAPTURE           12      /* Generic pcap_startcapture error */
 421 #define PCAP_ERR_ENDCAPTURE             13      /* Generic pcap_endcapture error */
 422 #define PCAP_ERR_RUNTIMETIMEOUT         14      /* The RPCAP run-time timeout has expired */
 423 #define PCAP_ERR_SETSAMPLING            15      /* Error during the settings of sampling parameters */
 424 #define PCAP_ERR_WRONGMSG               16      /* The other end endpoint sent a message which has not been recognized */
 425 #define PCAP_ERR_WRONGVER               17      /* The other end endpoint has a version number that is not compatible with our */
 426 #define PCAP_ERR_AUTH_FAILED            18      /* The user couldn't be authenticated */
 427 #define PCAP_ERR_TLS_REQUIRED           19      /* The server requires TLS to connect */
 428 #define PCAP_ERR_AUTH_TYPE_NOTSUP       20      /* The authentication type isn't supported */
 429
 430 /*
 431  * \brief Buffer used by socket functions to send-receive packets.
 432  * In case you plan to have messages larger than this value, you have to increase it.
 433  */
 434 #define RPCAP_NETBUF_SIZE 64000
 435
 436 /*********************************************************
 437  *                                                       *
 438  * Routines used by the rpcap client and rpcap daemon    *
 439  *                                                       *
 440  *********************************************************/
 441
 442 #include "sockutils.h"
 443 #include "sslutils.h"
 444
 445 extern void rpcap_createhdr(struct rpcap_header *header, uint8 ver, uint8 type, uint16 value, uint32 length);
 446 extern const char *rpcap_msg_type_string(uint8 type);
 447 extern int rpcap_senderror(SOCKET sock, SSL *ssl, uint8 ver, uint16 errcode, const char *error, char *errbuf);
 448
 449 #endif