2 This file is part of GNUnet
3 Copyright (C) 2010-2014 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your 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 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
20 * @author Philipp Toelke
21 * @author Christian Grothoff
24 * API for helper library to parse DNS packets.
26 * @defgroup dns-parser DNS parser library
27 * Helper library to parse DNS packets.
30 #ifndef GNUNET_DNSPARSER_LIB_H
31 #define GNUNET_DNSPARSER_LIB_H
33 #include "gnunet_util_lib.h"
36 * Maximum length of a label in DNS.
38 #define GNUNET_DNSPARSER_MAX_LABEL_LENGTH 63
41 * Maximum length of a name in DNS.
43 #define GNUNET_DNSPARSER_MAX_NAME_LENGTH 253
47 * A few common DNS types.
49 #define GNUNET_DNSPARSER_TYPE_ANY 0
50 #define GNUNET_DNSPARSER_TYPE_A 1
51 #define GNUNET_DNSPARSER_TYPE_NS 2
52 #define GNUNET_DNSPARSER_TYPE_CNAME 5
53 #define GNUNET_DNSPARSER_TYPE_SOA 6
54 #define GNUNET_DNSPARSER_TYPE_PTR 12
55 #define GNUNET_DNSPARSER_TYPE_MX 15
56 #define GNUNET_DNSPARSER_TYPE_TXT 16
57 #define GNUNET_DNSPARSER_TYPE_RP 17
58 #define GNUNET_DNSPARSER_TYPE_AFSDB 18
59 #define GNUNET_DNSPARSER_TYPE_SIG 24
60 #define GNUNET_DNSPARSER_TYPE_KEY 25
61 #define GNUNET_DNSPARSER_TYPE_AAAA 28
62 #define GNUNET_DNSPARSER_TYPE_LOC 29
63 #define GNUNET_DNSPARSER_TYPE_SRV 33
64 #define GNUNET_DNSPARSER_TYPE_NAPTR 35
65 #define GNUNET_DNSPARSER_TYPE_KX 36
66 #define GNUNET_DNSPARSER_TYPE_CERT 37
67 #define GNUNET_DNSPARSER_TYPE_DNAME 39
68 #define GNUNET_DNSPARSER_TYPE_APL 42
69 #define GNUNET_DNSPARSER_TYPE_DS 43
70 #define GNUNET_DNSPARSER_TYPE_SSHFP 44
71 #define GNUNET_DNSPARSER_TYPE_IPSECKEY 45
72 #define GNUNET_DNSPARSER_TYPE_RRSIG 46
73 #define GNUNET_DNSPARSER_TYPE_NSEC 47
74 #define GNUNET_DNSPARSER_TYPE_DNSKEY 48
75 #define GNUNET_DNSPARSER_TYPE_DHCID 49
76 #define GNUNET_DNSPARSER_TYPE_NSEC3 50
77 #define GNUNET_DNSPARSER_TYPE_NSEC3PARAM 51
78 #define GNUNET_DNSPARSER_TYPE_TLSA 52
79 #define GNUNET_DNSPARSER_TYPE_HIP 55
80 #define GNUNET_DNSPARSER_TYPE_CDS 59
81 #define GNUNET_DNSPARSER_TYPE_CDNSKEY 60
82 #define GNUNET_DNSPARSER_TYPE_OPENPGPKEY 61
83 #define GNUNET_DNSPARSER_TYPE_TKEY 249
84 #define GNUNET_DNSPARSER_TYPE_TSIG 250
85 #define GNUNET_DNSPARSER_TYPE_ALL 255
86 #define GNUNET_DNSPARSER_TYPE_URI 256
87 #define GNUNET_DNSPARSER_TYPE_TA 32768
92 struct GNUNET_DNSPARSER_Query
96 * Name of the record that the query is for (0-terminated).
97 * In UTF-8 format. The library will convert from and to DNS-IDNA
98 * as necessary. Use #GNUNET_DNSPARSER_check_label() to test if an
99 * individual label is well-formed. If a given name is not well-formed,
100 * creating the DNS packet will fail.
105 * See GNUNET_DNSPARSER_TYPE_*.
110 * See GNUNET_TUN_DNS_CLASS_*.
112 uint16_t dns_traffic_class;
118 * Information from MX records (RFC 1035).
120 struct GNUNET_DNSPARSER_MxRecord
124 * Preference for this entry (lower value is higher preference).
129 * Name of the mail server.
130 * In UTF-8 format. The library will convert from and to DNS-IDNA
131 * as necessary. Use #GNUNET_DNSPARSER_check_label() to test if an
132 * individual label is well-formed. If a given name is not well-formed,
133 * creating the DNS packet will fail.
141 * Information from SRV records (RFC 2782).
143 struct GNUNET_DNSPARSER_SrvRecord
147 * Hostname offering the service.
148 * In UTF-8 format. The library will convert from and to DNS-IDNA
149 * as necessary. Use #GNUNET_DNSPARSER_check_label() to test if an
150 * individual label is well-formed. If a given name is not well-formed,
151 * creating the DNS packet will fail.
156 * Preference for this entry (lower value is higher preference). Clients
157 * will contact hosts from the lowest-priority group first and fall back
158 * to higher priorities if the low-priority entries are unavailable.
163 * Relative weight for records with the same priority. Clients will use
164 * the hosts of the same (lowest) priority with a probability proportional
165 * to the weight given.
170 * TCP or UDP port of the service.
178 * DNS CERT types as defined in RFC 4398.
180 enum GNUNET_DNSPARSER_CertType
185 GNUNET_DNSPARSER_CERTTYPE_RESERVED = 0,
188 * An x509 PKIX certificate
190 GNUNET_DNSPARSER_CERTTYPE_PKIX = 1,
195 GNUNET_DNSPARSER_CERTTYPE_SKPI = 2,
200 GNUNET_DNSPARSER_CERTTYPE_PGP = 3,
203 * An x509 PKIX cert URL
205 GNUNET_DNSPARSER_CERTTYPE_IPKIX = 4,
210 GNUNET_DNSPARSER_CERTTYPE_ISKPI = 5,
213 * A PGP cert fingerprint and URL
215 GNUNET_DNSPARSER_CERTTYPE_IPGP = 6,
218 * An attribute Certificate
220 GNUNET_DNSPARSER_CERTTYPE_ACPKIX = 7,
223 * An attribute cert URL
225 GNUNET_DNSPARSER_CERTTYPE_IACKPIX = 8
230 * DNSCERT algorithms as defined in http://www.iana.org/assignments/
231 * dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml, under dns-sec-alg-numbers-1
233 enum GNUNET_DNSPARSER_CertAlgorithm
238 GNUNET_DNSPARSER_CERTALGO_UNDEFINED = 0,
243 GNUNET_DNSPARSER_CERTALGO_RSAMD5 = 1,
248 GNUNET_DNSPARSER_CERTALGO_DH = 2,
253 GNUNET_DNSPARSER_CERTALGO_DSASHA = 3,
258 GNUNET_DNSPARSER_CERTALGO_RSRVD4 = 4,
263 GNUNET_DNSPARSER_CERTALGO_RSASHA = 5,
268 GNUNET_DNSPARSER_CERTALGO_DSANSEC3 = 6,
273 GNUNET_DNSPARSER_CERTALGO_RSANSEC3 = 7,
278 GNUNET_DNSPARSER_CERTALGO_RSASHA256 = 8,
283 GNUNET_DNSPARSER_CERTALGO_RSRVD9 = 9,
288 GNUNET_DNSPARSER_CERTALGO_RSASHA512 = 10,
293 GNUNET_DNSPARSER_CERTALGO_GOST_R34 = 12,
296 * ECDSA Curve P-256/SHA256
298 GNUNET_DNSPARSER_CERTALGO_ECDSA_P256SHA256 = 13,
301 * ECDSA Curve P-384/SHA384
303 GNUNET_DNSPARSER_CERTALGO_ECDSA_P384SHA384 = 14
309 * Information from CERT records (RFC 4034).
311 struct GNUNET_DNSPARSER_CertRecord
317 enum GNUNET_DNSPARSER_CertType cert_type;
327 enum GNUNET_DNSPARSER_CertAlgorithm algorithm;
330 * Number of bytes in @e certificate_data
332 size_t certificate_size;
335 * Data of the certificate.
337 char *certificate_data;
343 * Information from SOA records (RFC 1035).
345 struct GNUNET_DNSPARSER_SoaRecord
349 * The domainname of the name server that was the
350 * original or primary source of data for this zone.
351 * In UTF-8 format. The library will convert from and to DNS-IDNA
352 * as necessary. Use #GNUNET_DNSPARSER_check_label() to test if an
353 * individual label is well-formed. If a given name is not well-formed,
354 * creating the DNS packet will fail.
359 * A domainname which specifies the mailbox of the
360 * person responsible for this zone.
361 * In UTF-8 format. The library will convert from and to DNS-IDNA
362 * as necessary. Use #GNUNET_DNSPARSER_check_label() to test if an
363 * individual label is well-formed. If a given name is not well-formed,
364 * creating the DNS packet will fail.
369 * The version number of the original copy of the zone.
374 * Time interval before the zone should be refreshed.
379 * Time interval that should elapse before a failed refresh should
385 * Time value that specifies the upper limit on the time interval
386 * that can elapse before the zone is no longer authoritative.
391 * The bit minimum TTL field that should be exported with any RR
394 uint32_t minimum_ttl;
400 * Binary record information (unparsed).
402 struct GNUNET_DNSPARSER_RawRecord
406 * Binary record data.
411 * Number of bytes in data.
418 * A DNS response record.
420 struct GNUNET_DNSPARSER_Record
424 * Name of the record that the query is for (0-terminated).
425 * In UTF-8 format. The library will convert from and to DNS-IDNA
426 * as necessary. Use #GNUNET_DNSPARSER_check_label() to test if an
427 * individual label is well-formed. If a given name is not well-formed,
428 * creating the DNS packet will fail.
433 * Payload of the record (which one of these is valid depends on the 'type').
439 * For NS, CNAME and PTR records, this is the uncompressed 0-terminated hostname.
440 * In UTF-8 format. The library will convert from and to DNS-IDNA
441 * as necessary. Use #GNUNET_DNSPARSER_check_label() to test if an
442 * individual label is well-formed. If a given name is not well-formed,
443 * creating the DNS packet will fail.
448 * SOA data for SOA records.
450 struct GNUNET_DNSPARSER_SoaRecord *soa;
453 * CERT data for CERT records.
455 struct GNUNET_DNSPARSER_CertRecord *cert;
458 * MX data for MX records.
460 struct GNUNET_DNSPARSER_MxRecord *mx;
463 * SRV data for SRV records.
465 struct GNUNET_DNSPARSER_SrvRecord *srv;
468 * Raw data for all other types.
470 struct GNUNET_DNSPARSER_RawRecord raw;
476 * When does the record expire?
478 struct GNUNET_TIME_Absolute expiration_time;
481 * See GNUNET_DNSPARSER_TYPE_*.
486 * See GNUNET_TUN_DNS_CLASS_*.
488 uint16_t dns_traffic_class;
494 * Easy-to-process, parsed version of a DNS packet.
496 struct GNUNET_DNSPARSER_Packet
499 * Array of all queries in the packet, must contain "num_queries" entries.
501 struct GNUNET_DNSPARSER_Query *queries;
504 * Array of all answers in the packet, must contain "num_answers" entries.
506 struct GNUNET_DNSPARSER_Record *answers;
509 * Array of all authority records in the packet, must contain "num_authority_records" entries.
511 struct GNUNET_DNSPARSER_Record *authority_records;
514 * Array of all additional answers in the packet, must contain "num_additional_records" entries.
516 struct GNUNET_DNSPARSER_Record *additional_records;
519 * Number of queries in the packet.
521 unsigned int num_queries;
524 * Number of answers in the packet, should be 0 for queries.
526 unsigned int num_answers;
529 * Number of authoritative answers in the packet, should be 0 for queries.
531 unsigned int num_authority_records;
534 * Number of additional records in the packet, should be 0 for queries.
536 unsigned int num_additional_records;
539 * Bitfield of DNS flags.
541 struct GNUNET_TUN_DnsFlags flags;
544 * DNS ID (to match replies to requests).
552 * Check if a label in UTF-8 format can be coded into valid IDNA.
553 * This can fail if the ASCII-conversion becomes longer than 63 characters.
555 * @param label label to check (UTF-8 string)
556 * @return #GNUNET_OK if the label can be converted to IDNA,
557 * #GNUNET_SYSERR if the label is not valid for DNS names
560 GNUNET_DNSPARSER_check_label (const char *label);
564 * Check if a hostname in UTF-8 format can be coded into valid IDNA.
565 * This can fail if a label becomes longer than 63 characters or if
566 * the entire name exceeds 253 characters.
568 * @param name name to check (UTF-8 string)
569 * @return #GNUNET_OK if the label can be converted to IDNA,
570 * #GNUNET_SYSERR if the label is not valid for DNS names
573 GNUNET_DNSPARSER_check_name (const char *name);
577 * Parse a UDP payload of a DNS packet in to a nice struct for further
578 * processing and manipulation.
580 * @param udp_payload wire-format of the DNS packet
581 * @param udp_payload_length number of bytes in @a udp_payload
582 * @return NULL on error, otherwise the parsed packet
584 struct GNUNET_DNSPARSER_Packet *
585 GNUNET_DNSPARSER_parse (const char *udp_payload,
586 size_t udp_payload_length);
590 * Free memory taken by a packet.
592 * @param p packet to free
595 GNUNET_DNSPARSER_free_packet (struct GNUNET_DNSPARSER_Packet *p);
599 * Given a DNS packet @a p, generate the corresponding UDP payload.
600 * Note that we do not attempt to pack the strings with pointers
601 * as this would complicate the code and this is about being
602 * simple and secure, not fast, fancy and broken like bind.
604 * @param p packet to pack
605 * @param max maximum allowed size for the resulting UDP payload
606 * @param buf set to a buffer with the packed message
607 * @param buf_length set to the length of @a buf
608 * @return #GNUNET_SYSERR if @a p is invalid
609 * #GNUNET_NO if @a p was truncated (but there is still a result in @a buf)
610 * #GNUNET_OK if @a p was packed completely into @a buf
613 GNUNET_DNSPARSER_pack (const struct GNUNET_DNSPARSER_Packet *p,
618 /* ***************** low-level packing API ******************** */
621 * Add a DNS name to the UDP packet at the given location, converting
622 * the name to IDNA notation as necessary.
624 * @param dst where to write the name (UDP packet)
625 * @param dst_len number of bytes in @a dst
626 * @param off pointer to offset where to write the name (increment by bytes used)
627 * must not be changed if there is an error
628 * @param name name to write
629 * @return #GNUNET_SYSERR if @a name is invalid
630 * #GNUNET_NO if @a name did not fit
631 * #GNUNET_OK if @a name was added to @a dst
634 GNUNET_DNSPARSER_builder_add_name (char *dst,
641 * Add a DNS query to the UDP packet at the given location.
643 * @param dst where to write the query
644 * @param dst_len number of bytes in @a dst
645 * @param off pointer to offset where to write the query (increment by bytes used)
646 * must not be changed if there is an error
647 * @param query query to write
648 * @return #GNUNET_SYSERR if @a query is invalid
649 * #GNUNET_NO if @a query did not fit
650 * #GNUNET_OK if @a query was added to @a dst
653 GNUNET_DNSPARSER_builder_add_query (char *dst,
656 const struct GNUNET_DNSPARSER_Query *query);
660 * Add an MX record to the UDP packet at the given location.
662 * @param dst where to write the mx record
663 * @param dst_len number of bytes in @a dst
664 * @param off pointer to offset where to write the mx information (increment by bytes used);
665 * can also change if there was an error
666 * @param mx mx information to write
667 * @return #GNUNET_SYSERR if @a mx is invalid
668 * #GNUNET_NO if @a mx did not fit
669 * #GNUNET_OK if @a mx was added to @a dst
672 GNUNET_DNSPARSER_builder_add_mx (char *dst,
675 const struct GNUNET_DNSPARSER_MxRecord *mx);
679 * Add an SOA record to the UDP packet at the given location.
681 * @param dst where to write the SOA record
682 * @param dst_len number of bytes in @a dst
683 * @param off pointer to offset where to write the SOA information (increment by bytes used)
684 * can also change if there was an error
685 * @param soa SOA information to write
686 * @return #GNUNET_SYSERR if @a soa is invalid
687 * #GNUNET_NO if @a soa did not fit
688 * #GNUNET_OK if @a soa was added to @a dst
691 GNUNET_DNSPARSER_builder_add_soa (char *dst,
694 const struct GNUNET_DNSPARSER_SoaRecord *soa);
698 * Add CERT record to the UDP packet at the given location.
700 * @param dst where to write the CERT record
701 * @param dst_len number of bytes in @a dst
702 * @param off pointer to offset where to write the CERT information (increment by bytes used)
703 * can also change if there was an error
704 * @param cert CERT information to write
705 * @return #GNUNET_SYSERR if @a soa is invalid
706 * #GNUNET_NO if @a soa did not fit
707 * #GNUNET_OK if @a soa was added to @a dst
710 GNUNET_DNSPARSER_builder_add_cert (char *dst,
713 const struct GNUNET_DNSPARSER_CertRecord *cert);
717 * Add an SRV record to the UDP packet at the given location.
719 * @param dst where to write the SRV record
720 * @param dst_len number of bytes in @a dst
721 * @param off pointer to offset where to write the SRV information (increment by bytes used)
722 * can also change if there was an error
723 * @param srv SRV information to write
724 * @return #GNUNET_SYSERR if @a srv is invalid
725 * #GNUNET_NO if @a srv did not fit
726 * #GNUNET_OK if @a srv was added to @a dst
729 GNUNET_DNSPARSER_builder_add_srv (char *dst,
732 const struct GNUNET_DNSPARSER_SrvRecord *srv);
734 /* ***************** low-level parsing API ******************** */
737 * Parse a DNS record entry.
739 * @param udp_payload entire UDP payload
740 * @param udp_payload_length length of @a udp_payload
741 * @param off pointer to the offset of the record to parse in the udp_payload (to be
742 * incremented by the size of the record)
743 * @param r where to write the record information
744 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the record is malformed
747 GNUNET_DNSPARSER_parse_record (const char *udp_payload,
748 size_t udp_payload_length,
750 struct GNUNET_DNSPARSER_Record *r);
754 * Parse name inside of a DNS query or record.
756 * @param udp_payload entire UDP payload
757 * @param udp_payload_length length of @a udp_payload
758 * @param off pointer to the offset of the name to parse in the udp_payload (to be
759 * incremented by the size of the name)
760 * @return name as 0-terminated C string on success, NULL if the payload is malformed
763 GNUNET_DNSPARSER_parse_name (const char *udp_payload,
764 size_t udp_payload_length,
769 * Parse a DNS query entry.
771 * @param udp_payload entire UDP payload
772 * @param udp_payload_length length of @a udp_payload
773 * @param off pointer to the offset of the query to parse in the udp_payload (to be
774 * incremented by the size of the query)
775 * @param q where to write the query information
776 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the query is malformed
779 GNUNET_DNSPARSER_parse_query (const char *udp_payload,
780 size_t udp_payload_length,
782 struct GNUNET_DNSPARSER_Query *q);
786 * Parse a DNS SOA record.
788 * @param udp_payload reference to UDP packet
789 * @param udp_payload_length length of @a udp_payload
790 * @param off pointer to the offset of the query to parse in the SOA record (to be
791 * incremented by the size of the record), unchanged on error
792 * @return the parsed SOA record, NULL on error
794 struct GNUNET_DNSPARSER_SoaRecord *
795 GNUNET_DNSPARSER_parse_soa (const char *udp_payload,
796 size_t udp_payload_length,
801 * Parse a DNS CERT record.
803 * @param udp_payload reference to UDP packet
804 * @param udp_payload_length length of @a udp_payload
805 * @param off pointer to the offset of the query to parse in the CERT record (to be
806 * incremented by the size of the record), unchanged on error
807 * @return the parsed CERT record, NULL on error
809 struct GNUNET_DNSPARSER_CertRecord *
810 GNUNET_DNSPARSER_parse_cert (const char *udp_payload,
811 size_t udp_payload_length,
816 * Parse a DNS MX record.
818 * @param udp_payload reference to UDP packet
819 * @param udp_payload_length length of @a udp_payload
820 * @param off pointer to the offset of the query to parse in the MX record (to be
821 * incremented by the size of the record), unchanged on error
822 * @return the parsed MX record, NULL on error
824 struct GNUNET_DNSPARSER_MxRecord *
825 GNUNET_DNSPARSER_parse_mx (const char *udp_payload,
826 size_t udp_payload_length,
831 * Parse a DNS SRV record.
833 * @param udp_payload reference to UDP packet
834 * @param udp_payload_length length of @a udp_payload
835 * @param off pointer to the offset of the query to parse in the SRV record (to be
836 * incremented by the size of the record), unchanged on error
837 * @return the parsed SRV record, NULL on error
839 struct GNUNET_DNSPARSER_SrvRecord *
840 GNUNET_DNSPARSER_parse_srv (const char *udp_payload,
841 size_t udp_payload_length,
844 /* ***************** low-level duplication API ******************** */
847 * Duplicate (deep-copy) the given DNS record
849 * @param r the record
850 * @return the newly allocated record
852 struct GNUNET_DNSPARSER_Record *
853 GNUNET_DNSPARSER_duplicate_record (const struct GNUNET_DNSPARSER_Record *r);
857 * Duplicate (deep-copy) the given DNS record
859 * @param r the record
860 * @return the newly allocated record
862 struct GNUNET_DNSPARSER_SoaRecord *
863 GNUNET_DNSPARSER_duplicate_soa_record (const struct GNUNET_DNSPARSER_SoaRecord *r);
867 * Duplicate (deep-copy) the given DNS record
869 * @param r the record
870 * @return the newly allocated record
872 struct GNUNET_DNSPARSER_CertRecord *
873 GNUNET_DNSPARSER_duplicate_cert_record (const struct GNUNET_DNSPARSER_CertRecord *r);
877 * Duplicate (deep-copy) the given DNS record
879 * @param r the record
880 * @return the newly allocated record
882 struct GNUNET_DNSPARSER_MxRecord *
883 GNUNET_DNSPARSER_duplicate_mx_record (const struct GNUNET_DNSPARSER_MxRecord *r);
887 * Duplicate (deep-copy) the given DNS record
889 * @param r the record
890 * @return the newly allocated record
892 struct GNUNET_DNSPARSER_SrvRecord *
893 GNUNET_DNSPARSER_duplicate_srv_record (const struct GNUNET_DNSPARSER_SrvRecord *r);
896 /* ***************** low-level deallocation API ******************** */
899 * Free the given DNS record.
901 * @param r record to free
904 GNUNET_DNSPARSER_free_record (struct GNUNET_DNSPARSER_Record *r);
908 * Free MX information record.
910 * @param mx record to free
913 GNUNET_DNSPARSER_free_mx (struct GNUNET_DNSPARSER_MxRecord *mx);
917 * Free SRV information record.
919 * @param srv record to free
922 GNUNET_DNSPARSER_free_srv (struct GNUNET_DNSPARSER_SrvRecord *srv);
926 * Free SOA information record.
928 * @param soa record to free
931 GNUNET_DNSPARSER_free_soa (struct GNUNET_DNSPARSER_SoaRecord *soa);
935 * Free CERT information record.
937 * @param cert record to free
940 GNUNET_DNSPARSER_free_cert (struct GNUNET_DNSPARSER_CertRecord *cert);
944 * Convert a block of binary data to HEX.
946 * @param data binary data to convert
947 * @param data_size number of bytes in @a data
948 * @return HEX string (lower case)
951 GNUNET_DNSPARSER_bin_to_hex (const void *data,
956 * Convert a HEX string to block of binary data.
958 * @param hex HEX string to convert (may contain mixed case)
959 * @param data where to write result, must be
960 * at least `strlen(hex)/2` bytes long
961 * @return number of bytes written to data
964 GNUNET_DNSPARSER_hex_to_bin (const char *hex,
970 /** @} */ /* end of group */