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_dnsparser_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 #define GNUNET_DNSPARSER_TYPE_SRV 33
  45
  46 /**
  47  * A few common DNS classes (ok, only one is common, but I list a
  48  * couple more to make it clear what we're talking about here).
  49  */
  50 #define GNUNET_DNSPARSER_CLASS_INTERNET 1
  51 #define GNUNET_DNSPARSER_CLASS_CHAOS 3
  52 #define GNUNET_DNSPARSER_CLASS_HESIOD 4
  53
  54 #define GNUNET_DNSPARSER_OPCODE_QUERY 0
  55 #define GNUNET_DNSPARSER_OPCODE_INVERSE_QUERY 1
  56 #define GNUNET_DNSPARSER_OPCODE_STATUS 2
  57
  58 /**
  59  * RFC 1035 codes.
  60  */
  61 #define GNUNET_DNSPARSER_RETURN_CODE_NO_ERROR 0
  62 #define GNUNET_DNSPARSER_RETURN_CODE_FORMAT_ERROR 1
  63 #define GNUNET_DNSPARSER_RETURN_CODE_SERVER_FAILURE 2
  64 #define GNUNET_DNSPARSER_RETURN_CODE_NAME_ERROR 3
  65 #define GNUNET_DNSPARSER_RETURN_CODE_NOT_IMPLEMENTED 4
  66 #define GNUNET_DNSPARSER_RETURN_CODE_REFUSED 5
  67
  68 /**
  69  * RFC 2136 codes
  70  */
  71 #define GNUNET_DNSPARSER_RETURN_CODE_YXDOMAIN 6
  72 #define GNUNET_DNSPARSER_RETURN_CODE_YXRRSET 7
  73 #define GNUNET_DNSPARSER_RETURN_CODE_NXRRSET 8
  74 #define GNUNET_DNSPARSER_RETURN_CODE_NOT_AUTH 9
  75 #define GNUNET_DNSPARSER_RETURN_CODE_NOT_ZONE 10
  76
  77 /**
  78  * DNS flags (largely RFC 1035 / RFC 2136).
  79  */
  80 struct GNUNET_DNSPARSER_Flags
  81 {
  82   /**
  83    * Set to 1 if recursion is desired (client -> server)
  84    */
  85   unsigned int recursion_desired    : 1 GNUNET_PACKED;
  86
  87   /**
  88    * Set to 1 if message is truncated
  89    */
  90   unsigned int message_truncated    : 1 GNUNET_PACKED;
  91
  92   /**
  93    * Set to 1 if this is an authoritative answer
  94    */
  95   unsigned int authoritative_answer : 1 GNUNET_PACKED;
  96
  97   /**
  98    * See GNUNET_DNSPARSER_OPCODE_ defines.
  99    */
 100   unsigned int opcode               : 4 GNUNET_PACKED;
 101
 102   /**
 103    * query:0, response:1
 104    */
 105   unsigned int query_or_response    : 1 GNUNET_PACKED;
 106
 107   /**
 108    * See GNUNET_DNSPARSER_RETURN_CODE_ defines.
 109    */
 110   unsigned int return_code          : 4 GNUNET_PACKED;
 111
 112   /**
 113    * See RFC 4035.
 114    */
 115   unsigned int checking_disabled    : 1 GNUNET_PACKED;
 116
 117   /**
 118    * Response has been cryptographically verified, RFC 4035.
 119    */
 120   unsigned int authenticated_data   : 1 GNUNET_PACKED;
 121
 122   /**
 123    * Always zero.
 124    */
 125   unsigned int zero                 : 1 GNUNET_PACKED;
 126
 127   /**
 128    * Set to 1 if recursion is available (server -> client)
 129    */
 130   unsigned int recursion_available  : 1 GNUNET_PACKED;
 131
 132 } GNUNET_GCC_STRUCT_LAYOUT;
 133
 134
 135 /**
 136  * A DNS query.
 137  */
 138 struct GNUNET_DNSPARSER_Query
 139 {
 140
 141   /**
 142    * Name of the record that the query is for (0-terminated).
 143    */
 144   char *name;
 145
 146   /**
 147    * See GNUNET_DNSPARSER_TYPE_*.
 148    */
 149   uint16_t type;
 150
 151   /**
 152    * See GNUNET_DNSPARSER_CLASS_*.
 153    */
 154   uint16_t class;
 155
 156 };
 157
 158
 159 /**
 160  * Information from MX records (RFC 1035).
 161  */
 162 struct GNUNET_DNSPARSER_MxRecord
 163 {
 164
 165   /**
 166    * Preference for this entry (lower value is higher preference).
 167    */
 168   uint16_t preference;
 169
 170   /**
 171    * Name of the mail server.
 172    */
 173   char *mxhost;
 174
 175 };
 176
 177
 178 /**
 179  * Information from SRV records (RFC 2782).  The 'service', 'proto'
 180  * and 'domain_name' fields together give the DNS-name which for SRV
 181  * records is of the form "_$SERVICE._$PROTO.$DOMAIN_NAME".  The DNS
 182  * parser provides the full name in 'struct DNSPARSER_Record' and the
 183  * individual components in the respective fields of this struct.
 184  * When serializing, you CAN set the 'name' field of 'struct
 185  * GNUNET_DNSPARSER_Record' to NULL, in which case the DNSPARSER code
 186  * will populate 'name' from the 'service', 'proto' and 'domain_name'
 187  * fields in this struct.
 188  */
 189 struct GNUNET_DNSPARSER_SrvRecord
 190 {
 191
 192   /**
 193    * Service name without the underscore (!).  Note that RFC 6335 clarifies the
 194    * set of legal characters for service names.
 195    */
 196   char *service;
 197
 198   /**
 199    * Transport protocol (typcially "tcp" or "udp", but others might be allowed).
 200    * Without the underscore (!).
 201    */
 202   char *proto;
 203
 204   /**
 205    * Domain name for which the record is valid
 206    */
 207   char *domain_name;
 208
 209   /**
 210    * Hostname offering the service.
 211    */
 212   char *target;
 213
 214   /**
 215    * Preference for this entry (lower value is higher preference).  Clients
 216    * will contact hosts from the lowest-priority group first and fall back
 217    * to higher priorities if the low-priority entries are unavailable.
 218    */
 219   uint16_t priority;
 220
 221   /**
 222    * Relative weight for records with the same priority.  Clients will use
 223    * the hosts of the same (lowest) priority with a probability proportional
 224    * to the weight given.
 225    */
 226   uint16_t weight;
 227
 228   /**
 229    * TCP or UDP port of the service.
 230    */
 231   uint16_t port;
 232
 233 };
 234
 235
 236 /**
 237  * Information from SOA records (RFC 1035).
 238  */
 239 struct GNUNET_DNSPARSER_SoaRecord
 240 {
 241
 242   /**
 243    *The domainname of the name server that was the
 244    * original or primary source of data for this zone.
 245    */
 246   char *mname;
 247
 248   /**
 249    * A domainname which specifies the mailbox of the
 250    * person responsible for this zone.
 251    */
 252   char *rname;
 253
 254   /**
 255    * The version number of the original copy of the zone.
 256    */
 257   uint32_t serial;
 258
 259   /**
 260    * Time interval before the zone should be refreshed.
 261    */
 262   uint32_t refresh;
 263
 264   /**
 265    * Time interval that should elapse before a failed refresh should
 266    * be retried.
 267    */
 268   uint32_t retry;
 269
 270   /**
 271    * Time value that specifies the upper limit on the time interval
 272    * that can elapse before the zone is no longer authoritative.
 273    */
 274   uint32_t expire;
 275
 276   /**
 277    * The bit minimum TTL field that should be exported with any RR
 278    * from this zone.
 279    */
 280   uint32_t minimum_ttl;
 281
 282 };
 283
 284
 285 /**
 286  * Binary record information (unparsed).
 287  */
 288 struct GNUNET_DNSPARSER_RawRecord
 289 {
 290
 291   /**
 292    * Binary record data.
 293    */
 294   void *data;
 295
 296   /**
 297    * Number of bytes in data.
 298    */
 299   size_t data_len;
 300 };
 301
 302
 303 /**
 304  * A DNS response record.
 305  */
 306 struct GNUNET_DNSPARSER_Record
 307 {
 308
 309   /**
 310    * Name of the record that the query is for (0-terminated).
 311    */
 312   char *name;
 313
 314   /**
 315    * Payload of the record (which one of these is valid depends on the 'type').
 316    */
 317   union
 318   {
 319
 320     /**
 321      * For NS, CNAME and PTR records, this is the uncompressed 0-terminated hostname.
 322      */
 323     char *hostname;
 324
 325     /**
 326      * SOA data for SOA records.
 327      */
 328     struct GNUNET_DNSPARSER_SoaRecord *soa;
 329
 330     /**
 331      * MX data for MX records.
 332      */
 333     struct GNUNET_DNSPARSER_MxRecord *mx;
 334
 335     /**
 336      * SRV data for SRV records.
 337      */
 338     struct GNUNET_DNSPARSER_SrvRecord *srv;
 339
 340     /**
 341      * Raw data for all other types.
 342      */
 343     struct GNUNET_DNSPARSER_RawRecord raw;
 344
 345   } data;
 346
 347
 348   /**
 349    * When does the record expire?
 350    */
 351   struct GNUNET_TIME_Absolute expiration_time;
 352
 353   /**
 354    * See GNUNET_DNSPARSER_TYPE_*.
 355    */
 356   uint16_t type;
 357
 358   /**
 359    * See GNUNET_DNSPARSER_CLASS_*.
 360    */
 361   uint16_t class;
 362
 363 };
 364
 365
 366 /**
 367  * Easy-to-process, parsed version of a DNS packet.
 368  */
 369 struct GNUNET_DNSPARSER_Packet
 370 {
 371   /**
 372    * Array of all queries in the packet, must contain "num_queries" entries.
 373    */
 374   struct GNUNET_DNSPARSER_Query *queries;
 375
 376   /**
 377    * Array of all answers in the packet, must contain "num_answers" entries.
 378    */
 379   struct GNUNET_DNSPARSER_Record *answers;
 380
 381   /**
 382    * Array of all authority records in the packet, must contain "num_authority_records" entries.
 383    */
 384   struct GNUNET_DNSPARSER_Record *authority_records;
 385
 386   /**
 387    * Array of all additional answers in the packet, must contain "num_additional_records" entries.
 388    */
 389   struct GNUNET_DNSPARSER_Record *additional_records;
 390
 391   /**
 392    * Number of queries in the packet.
 393    */
 394   unsigned int num_queries;
 395
 396   /**
 397    * Number of answers in the packet, should be 0 for queries.
 398    */
 399   unsigned int num_answers;
 400
 401   /**
 402    * Number of authoritative answers in the packet, should be 0 for queries.
 403    */
 404   unsigned int num_authority_records;
 405
 406   /**
 407    * Number of additional records in the packet, should be 0 for queries.
 408    */
 409   unsigned int num_additional_records;
 410
 411   /**
 412    * Bitfield of DNS flags.
 413    */
 414   struct GNUNET_DNSPARSER_Flags flags;
 415
 416   /**
 417    * DNS ID (to match replies to requests).
 418    */
 419   uint16_t id;
 420
 421 };
 422
 423
 424 /**
 425  * Parse a UDP payload of a DNS packet in to a nice struct for further
 426  * processing and manipulation.
 427  *
 428  * @param udp_payload wire-format of the DNS packet
 429  * @param udp_payload_length number of bytes in udp_payload
 430  * @return NULL on error, otherwise the parsed packet
 431  */
 432 struct GNUNET_DNSPARSER_Packet *
 433 GNUNET_DNSPARSER_parse (const char *udp_payload,
 434                         size_t udp_payload_length);
 435
 436
 437 /**
 438  * Free memory taken by a packet.
 439  *
 440  * @param p packet to free
 441  */
 442 void
 443 GNUNET_DNSPARSER_free_packet (struct GNUNET_DNSPARSER_Packet *p);
 444
 445
 446 /**
 447  * Given a DNS packet, generate the corresponding UDP payload.
 448  *
 449  * @param p packet to pack
 450  * @param max maximum allowed size for the resulting UDP payload
 451  * @param buf set to a buffer with the packed message
 452  * @param buf_length set to the length of buf
 453  * @return GNUNET_SYSERR if 'p' is invalid
 454  *         GNUNET_NO if 'p' was truncated (but there is still a result in 'buf')
 455  *         GNUNET_OK if 'p' was packed completely into '*buf'
 456  */
 457 int
 458 GNUNET_DNSPARSER_pack (const struct GNUNET_DNSPARSER_Packet *p,
 459                        uint16_t max,
 460                        char **buf,
 461                        size_t *buf_length);
 462
 463
 464 #endif