2 This file is part of GNUnet
3 (C) 2010, 2011, 2012 Christian Grothoff (and other contributing authors)
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.
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.
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.
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
27 #ifndef GNUNET_DNSPARSER_LIB_H
28 #define GNUNET_DNSPARSER_LIB_H
31 #include "gnunet_common.h"
34 * A few common DNS types.
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
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).
49 #define GNUNET_DNSPARSER_CLASS_INTERNET 1
50 #define GNUNET_DNSPARSER_CLASS_CHAOS 3
51 #define GNUNET_DNSPARSER_CLASS_HESIOD 4
53 #define GNUNET_DNSPARSER_OPCODE_QUERY 0
54 #define GNUNET_DNSPARSER_OPCODE_INVERSE_QUERY 1
55 #define GNUNET_DNSPARSER_OPCODE_STATUS 2
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
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
77 * DNS flags (largely RFC 1035 / RFC 2136).
79 struct GNUNET_DNSPARSER_Flags
82 * Set to 1 if recursion is desired (client -> server)
84 unsigned int recursion_desired : 1 GNUNET_PACKED;
87 * Set to 1 if message is truncated
89 unsigned int message_truncated : 1 GNUNET_PACKED;
92 * Set to 1 if this is an authoritative answer
94 unsigned int authoritative_answer : 1 GNUNET_PACKED;
97 * See GNUNET_DNSPARSER_OPCODE_ defines.
99 unsigned int opcode : 4 GNUNET_PACKED;
102 * query:0, response:1
104 unsigned int query_or_response : 1 GNUNET_PACKED;
107 * See GNUNET_DNSPARSER_RETURN_CODE_ defines.
109 unsigned int return_code : 4 GNUNET_PACKED;
114 unsigned int checking_disabled : 1 GNUNET_PACKED;
117 * Response has been cryptographically verified, RFC 4035.
119 unsigned int authenticated_data : 1 GNUNET_PACKED;
124 unsigned int zero : 1 GNUNET_PACKED;
127 * Set to 1 if recursion is available (server -> client)
129 unsigned int recursion_available : 1 GNUNET_PACKED;
131 } GNUNET_GCC_STRUCT_LAYOUT;
137 struct GNUNET_DNSPARSER_Query
141 * Name of the record that the query is for (0-terminated).
146 * See GNUNET_DNSPARSER_TYPE_*.
151 * See GNUNET_DNSPARSER_CLASS_*.
159 * Information from MX records (RFC 1035).
161 struct GNUNET_DNSPARSER_MxRecord
165 * Preference for this entry (lower value is higher preference).
170 * Name of the mail server.
178 * Information from SOA records (RFC 1035).
180 struct GNUNET_DNSPARSER_SoaRecord
184 *The domainname of the name server that was the
185 * original or primary source of data for this zone.
190 * A domainname which specifies the mailbox of the
191 * person responsible for this zone.
196 * The version number of the original copy of the zone.
201 * Time interval before the zone should be refreshed.
206 * Time interval that should elapse before a failed refresh should
212 * Time value that specifies the upper limit on the time interval
213 * that can elapse before the zone is no longer authoritative.
218 * The bit minimum TTL field that should be exported with any RR
221 uint32_t minimum_ttl;
227 * Binary record information (unparsed).
229 struct GNUNET_DNSPARSER_RawRecord
233 * Binary record data.
238 * Number of bytes in data.
245 * A DNS response record.
247 struct GNUNET_DNSPARSER_Record
251 * Name of the record that the query is for (0-terminated).
259 * For NS, CNAME and PTR records, this is the uncompressed 0-terminated hostname.
264 * SOA data for SOA records.
266 struct GNUNET_DNSPARSER_SoaRecord *soa;
269 * MX data for MX records.
271 struct GNUNET_DNSPARSER_MxRecord *mx;
274 * Raw data for all other types.
276 struct GNUNET_DNSPARSER_RawRecord raw;
282 * When does the record expire?
284 struct GNUNET_TIME_Absolute expiration_time;
287 * See GNUNET_DNSPARSER_TYPE_*.
292 * See GNUNET_DNSPARSER_CLASS_*.
300 * Easy-to-process, parsed version of a DNS packet.
302 struct GNUNET_DNSPARSER_Packet
305 * Array of all queries in the packet, must contain "num_queries" entries.
307 struct GNUNET_DNSPARSER_Query *queries;
310 * Array of all answers in the packet, must contain "num_answers" entries.
312 struct GNUNET_DNSPARSER_Record *answers;
315 * Array of all authority records in the packet, must contain "num_authority_records" entries.
317 struct GNUNET_DNSPARSER_Record *authority_records;
320 * Array of all additional answers in the packet, must contain "num_additional_records" entries.
322 struct GNUNET_DNSPARSER_Record *additional_records;
325 * Number of queries in the packet.
327 unsigned int num_queries;
330 * Number of answers in the packet, should be 0 for queries.
332 unsigned int num_answers;
335 * Number of authoritative answers in the packet, should be 0 for queries.
337 unsigned int num_authority_records;
340 * Number of additional records in the packet, should be 0 for queries.
342 unsigned int num_additional_records;
345 * Bitfield of DNS flags.
347 struct GNUNET_DNSPARSER_Flags flags;
350 * DNS ID (to match replies to requests).
358 * Parse a UDP payload of a DNS packet in to a nice struct for further
359 * processing and manipulation.
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
365 struct GNUNET_DNSPARSER_Packet *
366 GNUNET_DNSPARSER_parse (const char *udp_payload,
367 size_t udp_payload_length);
371 * Free memory taken by a packet.
373 * @param p packet to free
376 GNUNET_DNSPARSER_free_packet (struct GNUNET_DNSPARSER_Packet *p);
380 * Given a DNS packet, generate the corresponding UDP payload.
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'
391 GNUNET_DNSPARSER_pack (const struct GNUNET_DNSPARSER_Packet *p,