packet-dccp.h

   1 /* packet-dcc.c
   2  * Protocol defs for Distributed Checksum Clearinghouse Protocol
   3  * DCC Home: http://www.rhyolite.com/anti-spam/dcc/
   4  *
   5  * Copyright 1999, Nathan Neulinger <nneul@umr.edu>
   6  *
   7  * $Id: packet-dccp.h,v 1.3 2002/08/28 21:00:08 jmayer Exp $
   8  *
   9  * Ethereal - Network traffic analyzer
  10  * By Gerald Combs <gerald@ethereal.com>
  11  * Copyright 1998 Gerald Combs
  12  *
  13  * Copied from packet-tftp.c
  14  *
  15  * This program is free software; you can redistribute it and/or
  16  * modify it under the terms of the GNU General Public License
  17  * as published by the Free Software Foundation; either version 2
  18  * of the License, or (at your option) any later version.
  19  *
  20  * This program is distributed in the hope that it will be useful,
  21  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  22  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23  * GNU General Public License for more details.
  24  *
  25  * You should have received a copy of the GNU General Public License
  26  * along with this program; if not, write to the Free Software
  27  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  28  */
  29
  30
  31 /* Inserted below is dcc_proto.h from the dcc source distribution, with the
  32         following changes made:
  33
  34 :%s/u_in*t16_t/guint16/g
  35 :%s/u_in*t32_t/guint32/g
  36 :%s/u_ch*ar/guchar/g
  37 :%s/in*t32_t/gint32/g
  38
  39 This includes more than is really necessary, but easier to just include whole
  40 header.
  41
  42 */
  43
  44
  45 /* Distributed Checksum Clearinghouse protocol
  46  *
  47  * Copyright (c) 2002 by Rhyolite Software
  48  *
  49  * Permission to use, copy, modify, and distribute this software for any
  50  * purpose with or without fee is hereby granted, provided that the above
  51  * copyright notice and this permission notice appear in all copies.
  52  *
  53  * THE SOFTWARE IS PROVIDED "AS IS" AND RHYOLITE SOFTWARE DISCLAIMS ALL
  54  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
  55  * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL RHYOLITE SOFTWARE
  56  * BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
  57  * OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  58  * WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  59  * ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  60  * SOFTWARE.
  61  *
  62  * Rhyolite Software DCC 1.0.53-1.45 $Revision: 1.3 $
  63  */
  64
  65 #ifndef DCC_PROTO_H
  66 #define DCC_PROTO_H
  67
  68
  69 #define DCC_PORT    6277                /* default UDP port #, MAPS in DTMF */
  70
  71
  72 /* No client's retransmission can be delayed by more than this
  73  * This matters for how long a DCC server must remember old requests
  74  * to recognize retransmissions */
  75 #define DCC_MAX_DELAY_SEC   30
  76
  77 typedef guint16 DCC_MS;
  78
  79 /* anonymous client delay */
  80 #define DCC_MAX_QDELAY_MS   (DCC_MAX_DELAY_SEC*1000)
  81 #define DCC_DEF_QDELAY_MS   0
  82
  83
  84 /* types of checksums */
  85 typedef enum {
  86     DCC_CK_INVALID  =0,                 /* deleted from database when seen */
  87     DCC_CK_IP       =1,                 /* MD5 of binary source IPv6 address */
  88     DCC_CK_ENV_FROM =2,                 /*  "  "  envelope Mail From value */
  89     DCC_CK_FROM     =3,                 /*  "  "  header From: line */
  90     DCC_CK_SUB      =4,                 /*  "  "  substitute header line */
  91     DCC_CK_MESSAGE_ID=5,                /*  "  "  header Message-ID: line */
  92     DCC_CK_RECEIVED =6,                 /*  "  "  last header Received: line */
  93     DCC_CK_BODY     =7,                 /*  "  "  body */
  94     DCC_CK_FUZ1     =8,                 /*  "  "  filtered body */
  95     DCC_CK_FUZ2     =9,                 /*  "  "     "      "   */
  96     DCC_CK_FUZ3     =10,                /*  "  "     "      "   */
  97     DCC_CK_FUZ4     =11,                /*  "  "     "      "   */
  98     DCC_CK_SRVR_ID  =12,                /* hostname for server-ID check */
  99     DCC_CK_ENV_TO   =13                 /* MD5 of envelope Rcpt To value */
 100 #   define DCC_CK_FLOD_PATH DCC_CK_ENV_TO   /* flooding path in server-IDs */
 101 } DCC_CK_TYPES;
 102 #define DCC_CK_TYPE_FIRST   DCC_CK_IP
 103 #define DCC_CK_TYPE_LAST    DCC_CK_ENV_TO
 104 #define DCC_NUM_CKS         DCC_CK_TYPE_LAST    /* # of valid types */
 105
 106 /* DCC_DIM_CKS dimensions arrays of checksum types including DCC_CK_INVALID
 107  * Beware that DCC_DIM_CKS is used in the database header. */
 108 #define DCC_DIM_CKS         (DCC_CK_TYPE_LAST+1)
 109
 110 /* Ensure that arrays of DCC_CKs contain an even number so that structures
 111  * containing them will have no extra structure packing */
 112 #define DCC_COMP_DIM_CKS    ((((DCC_NUM_CKS+1)+1)/2)*2) /* == DCC_DIM_CKS */
 113
 114 /* keep in the database longer than others */
 115 #define DCC_CK_LONG_TERM(t) ((t) >= DCC_CK_FUZ1 && (t) <= DCC_CK_FUZ4)
 116
 117 #define DCC_CK_IS_BODY(t) ((t) >= DCC_CK_BODY && (t) <= DCC_CK_FUZ4)
 118
 119 /* ok for users to talk about */
 120 #define DCC_CK_OK_USER(t) ((t) > DCC_CK_INVALID && (t) <= DCC_CK_FUZ4)
 121 /* ok in the database */
 122 #define DCC_CK_OK_DB(t) ((t) > DCC_CK_INVALID && (t) <= DCC_CK_TYPE_LAST)
 123 #define DCC_CK_OK_PROTO(t) DCC_CK_OK_USER(t)    /* ok from clients */
 124 #define DCC_CK_OK_FLOD(t) DCC_CK_OK_DB(t)   /* ok in floods */
 125
 126 typedef guchar DCC_CK_TYPE;
 127
 128
 129 typedef enum {
 130     DCC_OP_INVALID=0,
 131     DCC_OP_NOP,                         /* see if the server is alive */
 132     DCC_OP_REPORT,                      /* client reporting and querying */
 133     DCC_OP_QUERY,                       /* client querying */
 134     DCC_OP_QUERY_RESP,                  /* server responding */
 135     DCC_OP_ADMN,                        /* local control of the server */
 136     DCC_OP_OK,                          /* administrative operation ok */
 137     DCC_OP_ERROR,                       /* server failing or complaining */
 138     DCC_OP_DELETE                       /* delete some checksums */
 139 } DCC_OPS;
 140
 141 typedef guint32 DCC_CLNT_ID;
 142 #define DCC_ID_INVALID      0
 143 #define DCC_ID_ANON         1           /* anonymous (non-paying) client */
 144 #define DCC_ID_WHITE        2           /* white-listed */
 145 #define DCC_ID_COMP         3           /* compressed */
 146 #define DCC_SRVR_ID_MIN     100         /* below reserved for special uses */
 147 #define DCC_SRVR_ID_MAX     32767       /* below are servers--must be 2**n-1 */
 148 #define DCC_CLNT_ID_MIN     (DCC_SRVR_ID_MAX+1)
 149 #define DCC_CLNT_ID_MAX     16777215
 150 typedef guint16 DCC_SRVR_ID;
 151 #define DCC_SRVR_ID_AUTH (DCC_SRVR_ID_MAX+1)    /* client was authenticated */
 152
 153 /* client's identification of its transaction */
 154 typedef struct {
 155     guint32     h;                      /* client host ID, e.g. IP address */
 156     guint32     p;                      /* process ID, serial #, timestamp */
 157     guint32     r;                      /* report ID */
 158     guint32     t;                      /* client (re)transmission # */
 159 } DCC_OP_NUMS;
 160
 161 /* The inter-DCC server flooding algorithm depends on unique-per-server
 162  * timestamps to detect duplicates.  That imposes a requirement on
 163  * timestamps that they have resolution enough to separate reports
 164  * from clients arriving at any single server.
 165  * The timestamps are 48 bits consisting of 17 bits of 8's of microseconds
 166  * and 31 bits of seconds.  That's sufficient for the UNIX epoch.
 167  * If the DCC is still around in the 2030's (and in the unlikely case that
 168  * 8 microseconds are still fine enough), we can make the 31 bits be
 169  * an offset in a bigger window.
 170  */
 171 #define DCC_TS_USEC_RSHIFT  3
 172 #define DCC_TS_USEC_MULT    (1<<DCC_TS_USEC_RSHIFT)
 173 #define DCC_TS_SEC_LSHIFT   17
 174 #define DCC_TS_USEC_MASK    ((1<<DCC_TS_SEC_LSHIFT) - 1)
 175 typedef guchar DCC_TS[6];
 176
 177 /* The start of any DCC packet.
 178  *      The length and version are early, since they are they only fields
 179  *      that are constrained in future versions. */
 180 typedef struct {
 181     guint16     len;                    /* total DCC packet length (for TCP) */
 182     guchar      pkt_vers;               /* packet protocol version */
 183 #    define      DCC_PKT_VERSION        4
 184 #    define      DCC_PKT_VERSION_MIN    DCC_PKT_VERSION
 185 #    define      DCC_PKT_VERSION_MAX    DCC_PKT_VERSION
 186     guchar      op;                     /* one of DCC_OPS */
 187     /* Identify the transaction.
 188      *      Each client can have many hosts, each host can be multi-homed,
 189      *      and each host can be running many processes talking to the
 190      *      server.  Each packet needs to be uniquely numbered, so that the
 191      *      server can recognize as interchangable all of the (re)transmissions
 192      *      of a single report (rid) from a client process (pid) on a single
 193      *      host (hid), and the client can know which transmission (tid)
 194      *      produced a given server response to maintain the client's RTT
 195      *      value for the server. */
 196     DCC_CLNT_ID sender;                 /* official DCC client-ID */
 197     DCC_OP_NUMS op_nums;                /* op_num.t must be last */
 198 } DCC_HDR;
 199
 200 typedef guchar DCC_SIGNATURE[16];
 201
 202 typedef struct {
 203     DCC_HDR     hdr;
 204     DCC_SIGNATURE signature;
 205 } DCC_NOP;
 206
 207
 208 /* administrative requests from localhost
 209  *      These can be freely changed, because the administrative tools
 210  *      should match the daemon. */
 211 typedef enum {
 212     DCC_AOP_OK=-1,                      /* never really sent */
 213     DCC_AOP_STOP=1,                     /* stop gracefully */
 214     DCC_AOP_NEW_IDS,                    /* load keys and client-IDs */
 215     DCC_AOP_FLOD,                       /* start or stop flooding */
 216     DCC_AOP_DB_UNLOCK,                  /* start switch to new database */
 217     DCC_AOP_DB_NEW,                     /* finish switch to new database */
 218     DCC_AOP_STATS,                      /* return counters--val=buffer size */
 219     DCC_AOP_STATS_CLEAR,                /* return and zero counters */
 220     DCC_AOP_TRACE_ON,
 221     DCC_AOP_TRACE_OFF,
 222     DCC_AOP_CUR_CLIENTS                 /* some client IP addresses */
 223 } DCC_AOPS;
 224
 225 /* for DCC_AOP_FLOD */
 226 typedef enum {
 227     DCC_AOP_FLOD_CHECK=0,
 228     DCC_AOP_FLOD_SHUTDOWN,
 229     DCC_AOP_FLOD_HALT,
 230     DCC_AOP_FLOD_RESUME,
 231     DCC_AOP_FLOD_REWIND,
 232     DCC_AOP_FLOD_LIST,
 233     DCC_AOP_FLOD_STATS,
 234     DCC_AOP_FLOD_STATS_CLEAR
 235 } DCC_AOP_FLODS;
 236
 237 typedef struct {                        /* with operation DCC_OP_ADMN */
 238     DCC_HDR     hdr;
 239     gint32      date;                   /* seconds since epoch on caller */
 240     guint32     val;                    /* request type, buffer size, etc. */
 241     guchar      aop;                    /* one of DCC_AOPS */
 242     guchar      pad[3];
 243     DCC_SIGNATURE signature;
 244 } DCC_ADMN_REQ;
 245
 246 /* noisy response to some DCC_AOPS with operation DCC_OP_ADMN */
 247 typedef struct {
 248     guchar      addr[16];
 249     DCC_CLNT_ID id;
 250     guint32     last_used;
 251     guint32     requests;
 252 } DCC_ADMN_RESP_CLIENTS;
 253 typedef union {
 254     char        string[80*22];
 255     DCC_ADMN_RESP_CLIENTS clients[1];
 256 } DCC_ADMN_RESP_VAL;
 257 typedef struct {
 258     DCC_HDR     hdr;
 259     DCC_ADMN_RESP_VAL val;
 260     DCC_SIGNATURE signature;
 261 } DCC_ADMN_RESP;
 262
 263
 264 #define DCC_TRACE_ADMN_BIT  0x0001      /* administrative requests */
 265 #define DCC_TRACE_ANON_BIT  0x0002      /* anonymous client errors */
 266 #define DCC_TRACE_CLNT_BIT  0x0004      /* authenticated client errors */
 267 #define DCC_TRACE_RLIM_BIT  0x0008      /* rate limited messages */
 268 #define DCC_TRACE_QUERY_BIT 0x0010      /* all queries and reports */
 269 #define DCC_TRACE_RIDC_BIT  0x0020      /* RID cache messages */
 270 #define DCC_TRACE_FLOD_BIT  0x0040      /* input and output flooding */
 271 /* INFO must always be on */
 272 #define DCC_TRACE_ALL_BITS  (DCC_TRACE_ADMN_BIT | DCC_TRACE_ANON_BIT    \
 273                              | DCC_TRACE_CLNT_BIT | DCC_TRACE_RLIM_BIT  \
 274                              | DCC_TRACE_QUERY_BIT | DCC_TRACE_RIDC_BIT \
 275                              | DCC_TRACE_FLOD_BIT)
 276
 277
 278 typedef char DCC_BRAND[64];
 279
 280 /* administrative or NOP ok */
 281 typedef struct {
 282     DCC_HDR     hdr;
 283     guchar      max_pkt_vers;           /* can handle this version */
 284     guchar      unused;
 285     DCC_MS      qdelay_ms;
 286     DCC_BRAND   brand;                  /* identity or brandname of sender */
 287     DCC_SIGNATURE signature;
 288 } DCC_OK;
 289
 290
 291 /* a reported checksum from a client */
 292 typedef guchar DCC_SUM[16];             /* for now all have 16 bytes */
 293 typedef struct {
 294     DCC_CK_TYPE type;
 295     guchar      len;                    /* total length of this checksum */
 296     DCC_SUM     sum;
 297 } DCC_CK;
 298
 299 typedef guint32 DCC_TGTS;               /* database is limited to 24 bits */
 300 #define DCC_TGTS_TOO_MANY   0x00fffff0  /* >= 16777200 targets */
 301 #define DCC_TGTS_OK         0x00fffff1  /* certified not spam */
 302 #define DCC_TGTS_OK2        0x00fffff2  /* half certified not spam */
 303 #define DCC_TGTS_DEL        0x00fffff3  /* a deleted checksum */
 304 #define DCC_TGTS_INVALID    0x01000000
 305
 306 /* query or query/report packet from client to server */
 307 typedef struct {
 308     DCC_HDR     hdr;
 309     DCC_TGTS    tgts;                   /* # of addressees */
 310 #    define      DCC_QUERY_MAX DCC_DIM_CKS
 311     DCC_CK      cks[DCC_QUERY_MAX];     /* even to prevent structure padding */
 312     DCC_SIGNATURE signature;
 313 } DCC_QUERY_REPORT;
 314
 315
 316 typedef struct {
 317     DCC_TGTS    tgts[DCC_QUERY_MAX];    /* individual answers */
 318 } DCC_QUERY_RESP_BODY;
 319
 320 /* response to a query or query/report */
 321 typedef struct {
 322     DCC_HDR     hdr;
 323     DCC_QUERY_RESP_BODY body;
 324     DCC_SIGNATURE signature;
 325 } DCC_QUERY_RESP;
 326
 327
 328 /* DCC_OP_DELETE request to delete checksums */
 329 typedef struct {
 330     DCC_HDR     hdr;
 331     gint32      date;                   /* seconds since epoch on caller */
 332     DCC_CK      ck;
 333     guchar      pad[2];                 /* structure padding */
 334     DCC_SIGNATURE signature;
 335 } DCC_DELETE;
 336
 337
 338 /* error response from server to client */
 339 typedef struct {
 340     DCC_HDR     hdr;
 341 #    define      DCC_ERROR_MSG_LEN  128
 342     char        msg[DCC_ERROR_MSG_LEN];
 343     DCC_SIGNATURE signature;
 344 } DCC_ERROR;
 345
 346
 347 /* sender's position or serial number
 348  *      Only the sender understands sender positions except for these
 349  *      special values.  However, the special values imply that the position
 350  *      must be big endian. */
 351 typedef guchar DCC_FLOD_POS[8];
 352 /* special cases sent by the receiver back to the sender */
 353 #define DCC_FLOD_POS_END        0       /* receiver closing with message */
 354 #define DCC_FLOD_POS_END_REQ    1       /* receiver wants to stop */
 355 #define DCC_FLOD_POS_NOTE       2       /* receiver has a tracing message */
 356 #define DCC_FLOD_POS_COMPLAINT  3       /* receiver has a problem message */
 357 #define DCC_FLOD_POS_REWIND     4       /* receiver's database emptied */
 358 #define DCC_FLOD_POS_MIN        10
 359
 360 #define DCC_FLOD_OK_STR     "DCC flod ok: "
 361 #define DCC_FLOD_MAX_RESP   200
 362
 363 /* report forwarded among servers */
 364 typedef struct {
 365     DCC_FLOD_POS pos;
 366     guchar      tgts[sizeof(DCC_TGTS)];
 367     guchar      srvr_id_auth[sizeof(DCC_SRVR_ID)];  /* receiving server */
 368     DCC_TS      ts;                     /* date reported */
 369     guchar      num_cks;
 370     DCC_CK      cks[DCC_QUERY_MAX];
 371 } DCC_FLOD;
 372
 373 /* record of path taken by a report */
 374 #define DCC_NUM_FLOD_PATH ((int)(sizeof(DCC_SUM)/sizeof(DCC_SRVR_ID)))
 375 typedef struct {
 376     guchar      hi, lo;
 377 } DCC_FLOD_PATH_ID;
 378
 379 typedef struct {
 380     DCC_FLOD_POS z;
 381     char    msg[DCC_FLOD_MAX_RESP];
 382     char    null;
 383 } FLOD_END;
 384 typedef struct {
 385     DCC_FLOD_POS    op;
 386     guchar          len;
 387     char            str[DCC_FLOD_MAX_RESP];
 388 } FLOD_NOTE;
 389 #define FLOD_NOTE_OVHD ((int)sizeof(FLOD_NOTE)-DCC_FLOD_MAX_RESP)
 390
 391 #define DCC_FLOD_VERSION_STR_BASE   "DCC flod version "
 392 #define DCC_FLOD_VERSION5_STR       DCC_FLOD_VERSION_STR_BASE"5"
 393 #define DCC_FLOD_VERSION5           5
 394 #define DCC_FLOD_VERSION6_STR       DCC_FLOD_VERSION_STR_BASE"6"
 395 #define DCC_FLOD_VERSION6           6
 396 #define DCC_FLOD_VERSION7_STR       DCC_FLOD_VERSION_STR_BASE"7"
 397 #define DCC_FLOD_VERSION7           7
 398 #define DCC_FLOD_VERSION_DEF        0
 399 #define DCC_FLOD_VERSION_CUR_STR    DCC_FLOD_VERSION7_STR
 400 #define DCC_FLOD_VERSION_CUR        DCC_FLOD_VERSION7
 401 typedef struct {
 402 #    define DCC_FLOD_VERSION_STR_LEN 64
 403     char        str[DCC_FLOD_VERSION_STR_LEN];
 404     DCC_SRVR_ID sender_srvr_id;
 405     guchar      turn;
 406     guchar      unused[3];
 407 } DCC_FLOD_VERSION_BODY;
 408 typedef struct {
 409     DCC_FLOD_VERSION_BODY body;
 410     char        pad[256-sizeof(DCC_FLOD_VERSION_BODY)-sizeof(DCC_SIGNATURE)];
 411     DCC_SIGNATURE signature;
 412 } DCC_FLOD_VERSION_HDR;
 413
 414
 415 #endif /* DCC_PROTO_H   */