src/include/gnunet_dnsparser_lib.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2010, 2011, 2012 Christian Grothoff (and other contributing authors)
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 2, or (at your
   8       option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file include/gnunet_dnsparse_lib.h
  23  * @brief API for helper library to parse DNS packets.
  24  * @author Philipp Toelke
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_DNSPARSER_LIB_H
  28 #define GNUNET_DNSPARSER_LIB_H
  29
  30 #include "platform.h"
  31 #include "gnunet_common.h"
  32
  33 /**
  34  * A few common DNS types.
  35  */
  36 #define GNUNET_DNSPARSER_TYPE_A 1
  37 #define GNUNET_DNSPARSER_TYPE_NS 2
  38 #define GNUNET_DNSPARSER_TYPE_CNAME 5
  39 #define GNUNET_DNSPARSER_TYPE_SOA 6
  40 #define GNUNET_DNSPARSER_TYPE_PTR 12
  41 #define GNUNET_DNSPARSER_TYPE_MX 15
  42 #define GNUNET_DNSPARSER_TYPE_TXT 16
  43 #define GNUNET_DNSPARSER_TYPE_AAAA 28
  44
  45 /**
  46  * A few common DNS classes (ok, only one is common, but I list a
  47  * couple more to make it clear what we're talking about here).
  48  */
  49 #define GNUNET_DNSPARSER_CLASS_INTERNET 1
  50 #define GNUNET_DNSPARSER_CLASS_CHAOS 3
  51 #define GNUNET_DNSPARSER_CLASS_HESIOD 4
  52
  53 #define GNUNET_DNSPARSER_OPCODE_QUERY 0
  54 #define GNUNET_DNSPARSER_OPCODE_INVERSE_QUERY 1
  55 #define GNUNET_DNSPARSER_OPCODE_STATUS 2
  56
  57 /**
  58  * RFC 1035 codes.
  59  */
  60 #define GNUNET_DNSPARSER_RETURN_CODE_NO_ERROR 0
  61 #define GNUNET_DNSPARSER_RETURN_CODE_FORMAT_ERROR 1
  62 #define GNUNET_DNSPARSER_RETURN_CODE_SERVER_FAILURE 2
  63 #define GNUNET_DNSPARSER_RETURN_CODE_NAME_ERROR 3
  64 #define GNUNET_DNSPARSER_RETURN_CODE_NOT_IMPLEMENTED 4
  65 #define GNUNET_DNSPARSER_RETURN_CODE_REFUSED 5
  66
  67 /**
  68  * RFC 2136 codes
  69  */
  70 #define GNUNET_DNSPARSER_RETURN_CODE_YXDOMAIN 6
  71 #define GNUNET_DNSPARSER_RETURN_CODE_YXRRSET 7
  72 #define GNUNET_DNSPARSER_RETURN_CODE_NXRRSET 8
  73 #define GNUNET_DNSPARSER_RETURN_CODE_NOT_AUTH 9
  74 #define GNUNET_DNSPARSER_RETURN_CODE_NOT_ZONE 10
  75
  76 /**
  77  * DNS flags (largely RFC 1035 / RFC 2136).
  78  */
  79 struct GNUNET_DNSPARSER_Flags
  80 {
  81   /**
  82    * Set to 1 if recursion is desired (client -> server)
  83    */
  84   unsigned int recursion_desired    : 1 GNUNET_PACKED;
  85
  86   /**
  87    * Set to 1 if message is truncated
  88    */
  89   unsigned int message_truncated    : 1 GNUNET_PACKED;
  90
  91   /**
  92    * Set to 1 if this is an authoritative answer
  93    */
  94   unsigned int authoritative_answer : 1 GNUNET_PACKED;
  95
  96   /**
  97    * See GNUNET_DNSPARSER_OPCODE_ defines.
  98    */
  99   unsigned int opcode               : 4 GNUNET_PACKED;
 100
 101   /**
 102    * query:0, response:1
 103    */
 104   unsigned int query_or_response    : 1 GNUNET_PACKED;
 105
 106   /**
 107    * See GNUNET_DNSPARSER_RETURN_CODE_ defines.
 108    */
 109   unsigned int return_code          : 4 GNUNET_PACKED;
 110
 111   /**
 112    * See RFC 4035.
 113    */
 114   unsigned int checking_disabled    : 1 GNUNET_PACKED;
 115
 116   /**
 117    * Response has been cryptographically verified, RFC 4035.
 118    */
 119   unsigned int authenticated_data   : 1 GNUNET_PACKED;
 120
 121   /**
 122    * Always zero.
 123    */
 124   unsigned int zero                 : 1 GNUNET_PACKED;
 125
 126   /**
 127    * Set to 1 if recursion is available (server -> client)
 128    */
 129   unsigned int recursion_available  : 1 GNUNET_PACKED;
 130
 131 };
 132
 133
 134 /**
 135  * A DNS query.
 136  */
 137 struct GNUNET_DNSPARSER_Query
 138 {
 139
 140   /**
 141    * Name of the record that the query is for (0-terminated).
 142    */
 143   char *name;
 144
 145   /**
 146    * See GNUNET_DNSPARSER_TYPE_*.
 147    */
 148   uint16_t type;
 149
 150   /**
 151    * See GNUNET_DNSPARSER_CLASS_*.
 152    */
 153   uint16_t class;
 154
 155 };
 156
 157
 158 /**
 159  * Information from MX records (RFC 1035).
 160  */
 161 struct GNUNET_DNSPARSER_MxRecord
 162 {
 163
 164   /**
 165    * Preference for this entry (lower value is higher preference).
 166    */
 167   uint16_t preference;
 168
 169   /**
 170    * Name of the mail server.
 171    */
 172   char *mxhost;
 173
 174 };
 175
 176
 177 /**
 178  * Information from SOA records (RFC 1035).
 179  */
 180 struct GNUNET_DNSPARSER_SoaRecord
 181 {
 182
 183   /**
 184    *The domainname of the name server that was the
 185    * original or primary source of data for this zone.
 186    */
 187   char *mname;
 188
 189   /**
 190    * A domainname which specifies the mailbox of the
 191    * person responsible for this zone.
 192    */
 193   char *rname;
 194
 195   /**
 196    * The version number of the original copy of the zone.
 197    */
 198   uint32_t serial;
 199
 200   /**
 201    * Time interval before the zone should be refreshed.
 202    */
 203   uint32_t refresh;
 204
 205   /**
 206    * Time interval that should elapse before a failed refresh should
 207    * be retried.
 208    */
 209   uint32_t retry;
 210
 211   /**
 212    * Time value that specifies the upper limit on the time interval
 213    * that can elapse before the zone is no longer authoritative.
 214    */
 215   uint32_t expire;
 216
 217   /**
 218    * The bit minimum TTL field that should be exported with any RR
 219    * from this zone.
 220    */
 221   uint32_t minimum_ttl;
 222
 223 };
 224
 225
 226 /**
 227  * Binary record information (unparsed).
 228  */
 229 struct GNUNET_DNSPARSER_RawRecord
 230 {
 231
 232   /**
 233    * Binary record data.
 234    */
 235   void *data;
 236
 237   /**
 238    * Number of bytes in data.
 239    */
 240   size_t data_len;
 241 };
 242
 243
 244 /**
 245  * A DNS response record.
 246  */
 247 struct GNUNET_DNSPARSER_Record
 248 {
 249
 250   /**
 251    * Name of the record that the query is for (0-terminated).
 252    */
 253   char *name;
 254
 255   union
 256   {
 257
 258     /**
 259      * For NS, CNAME and PTR records, this is the uncompressed 0-terminated hostname.
 260      */
 261     char *hostname;
 262
 263     /**
 264      * SOA data for SOA records.
 265      */
 266     struct GNUNET_DNSPARSER_SoaRecord *soa;
 267
 268     /**
 269      * MX data for MX records.
 270      */
 271     struct GNUNET_DNSPARSER_MxRecord *mx;
 272
 273     /**
 274      * Raw data for all other types.
 275      */
 276     struct GNUNET_DNSPARSER_RawRecord raw;
 277
 278   } data;
 279
 280
 281   /**
 282    * When does the record expire?
 283    */
 284   struct GNUNET_TIME_Absolute expiration_time;
 285
 286   /**
 287    * See GNUNET_DNSPARSER_TYPE_*.
 288    */
 289   uint16_t type;
 290
 291   /**
 292    * See GNUNET_DNSPARSER_CLASS_*.
 293    */
 294   uint16_t class;
 295
 296 };
 297
 298
 299 /**
 300  * Easy-to-process, parsed version of a DNS packet.
 301  */
 302 struct GNUNET_DNSPARSER_Packet
 303 {
 304   /**
 305    * Array of all queries in the packet, must contain "num_queries" entries.
 306    */
 307   struct GNUNET_DNSPARSER_Query *queries;
 308
 309   /**
 310    * Array of all answers in the packet, must contain "num_answers" entries.
 311    */
 312   struct GNUNET_DNSPARSER_Record *answers;
 313
 314   /**
 315    * Array of all authority records in the packet, must contain "num_authority_records" entries.
 316    */
 317   struct GNUNET_DNSPARSER_Record *authority_records;
 318
 319   /**
 320    * Array of all additional answers in the packet, must contain "num_additional_records" entries.
 321    */
 322   struct GNUNET_DNSPARSER_Record *additional_records;
 323
 324   /**
 325    * Number of queries in the packet.
 326    */
 327   unsigned int num_queries;
 328
 329   /**
 330    * Number of answers in the packet, should be 0 for queries.
 331    */
 332   unsigned int num_answers;
 333
 334   /**
 335    * Number of authoritative answers in the packet, should be 0 for queries.
 336    */
 337   unsigned int num_authority_records;
 338
 339   /**
 340    * Number of additional records in the packet, should be 0 for queries.
 341    */
 342   unsigned int num_additional_records;
 343
 344   /**
 345    * Bitfield of DNS flags.
 346    */
 347   struct GNUNET_DNSPARSER_Flags flags;
 348
 349   /**
 350    * DNS ID (to match replies to requests).
 351    */
 352   uint16_t id;
 353
 354 };
 355
 356
 357 /**
 358  * Parse a UDP payload of a DNS packet in to a nice struct for further
 359  * processing and manipulation.
 360  *
 361  * @param udp_payload wire-format of the DNS packet
 362  * @param udp_payload_length number of bytes in udp_payload
 363  * @return NULL on error, otherwise the parsed packet
 364  */
 365 struct GNUNET_DNSPARSER_Packet *
 366 GNUNET_DNSPARSER_parse (const char *udp_payload,
 367                         size_t udp_payload_length);
 368
 369
 370 /**
 371  * Free memory taken by a packet.
 372  *
 373  * @param p packet to free
 374  */
 375 void
 376 GNUNET_DNSPARSER_free_packet (struct GNUNET_DNSPARSER_Packet *p);
 377
 378
 379 /**
 380  * Given a DNS packet, generate the corresponding UDP payload.
 381  *
 382  * @param p packet to pack
 383  * @param max maximum allowed size for the resulting UDP payload
 384  * @param buf set to a buffer with the packed message
 385  * @param buf_length set to the length of buf
 386  * @return GNUNET_SYSERR if 'p' is invalid
 387  *         GNUNET_NO if 'p' was truncated (but there is still a result in 'buf')
 388  *         GNUNET_OK if 'p' was packed completely into '*buf'
 389  */
 390 int
 391 GNUNET_DNSPARSER_pack (const struct GNUNET_DNSPARSER_Packet *p,
 392                        uint16_t max,
 393                        char **buf,
 394                        size_t *buf_length);
 395
 396
 397 #endif