src/include/gnunet_dnsparser_lib.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2010-2014 GNUnet e.V.
   4
   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.
   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       Affero General Public License for more details.
  14
  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/>.
  17  */
  18
  19 /**
  20  * @author Philipp Toelke
  21  * @author Christian Grothoff
  22  *
  23  * @file
  24  * API for helper library to parse DNS packets.
  25  *
  26  * @defgroup dns-parser  DNS parser library
  27  * Helper library to parse DNS packets.
  28  * @{
  29  */
  30 #ifndef GNUNET_DNSPARSER_LIB_H
  31 #define GNUNET_DNSPARSER_LIB_H
  32
  33 #include "gnunet_util_lib.h"
  34 #include "gnunet_tun_lib.h"
  35
  36 /**
  37  * Maximum length of a label in DNS.
  38  */
  39 #define GNUNET_DNSPARSER_MAX_LABEL_LENGTH 63
  40
  41 /**
  42  * Maximum length of a name in DNS.
  43  */
  44 #define GNUNET_DNSPARSER_MAX_NAME_LENGTH 253
  45
  46
  47 /**
  48  * A few common DNS types.
  49  */
  50 #define GNUNET_DNSPARSER_TYPE_ANY 0
  51 #define GNUNET_DNSPARSER_TYPE_A 1
  52 #define GNUNET_DNSPARSER_TYPE_NS 2
  53 #define GNUNET_DNSPARSER_TYPE_CNAME 5
  54 #define GNUNET_DNSPARSER_TYPE_SOA 6
  55 #define GNUNET_DNSPARSER_TYPE_PTR 12
  56 #define GNUNET_DNSPARSER_TYPE_MX 15
  57 #define GNUNET_DNSPARSER_TYPE_TXT 16
  58 #define GNUNET_DNSPARSER_TYPE_RP 17
  59 #define GNUNET_DNSPARSER_TYPE_AFSDB 18
  60 #define GNUNET_DNSPARSER_TYPE_SIG 24
  61 #define GNUNET_DNSPARSER_TYPE_KEY 25
  62 #define GNUNET_DNSPARSER_TYPE_AAAA 28
  63 #define GNUNET_DNSPARSER_TYPE_LOC 29
  64 #define GNUNET_DNSPARSER_TYPE_SRV 33
  65 #define GNUNET_DNSPARSER_TYPE_NAPTR 35
  66 #define GNUNET_DNSPARSER_TYPE_KX 36
  67 #define GNUNET_DNSPARSER_TYPE_CERT 37
  68 #define GNUNET_DNSPARSER_TYPE_DNAME 39
  69 #define GNUNET_DNSPARSER_TYPE_APL 42
  70 #define GNUNET_DNSPARSER_TYPE_DS 43
  71 #define GNUNET_DNSPARSER_TYPE_SSHFP 44
  72 #define GNUNET_DNSPARSER_TYPE_IPSECKEY 45
  73 #define GNUNET_DNSPARSER_TYPE_RRSIG 46
  74 #define GNUNET_DNSPARSER_TYPE_NSEC 47
  75 #define GNUNET_DNSPARSER_TYPE_DNSKEY 48
  76 #define GNUNET_DNSPARSER_TYPE_DHCID 49
  77 #define GNUNET_DNSPARSER_TYPE_NSEC3 50
  78 #define GNUNET_DNSPARSER_TYPE_NSEC3PARAM 51
  79 #define GNUNET_DNSPARSER_TYPE_TLSA 52
  80 #define GNUNET_DNSPARSER_TYPE_HIP 55
  81 #define GNUNET_DNSPARSER_TYPE_CDS 59
  82 #define GNUNET_DNSPARSER_TYPE_CDNSKEY 60
  83 #define GNUNET_DNSPARSER_TYPE_OPENPGPKEY 61
  84 #define GNUNET_DNSPARSER_TYPE_TKEY 249
  85 #define GNUNET_DNSPARSER_TYPE_TSIG 250
  86 #define GNUNET_DNSPARSER_TYPE_URI 256
  87 #define GNUNET_DNSPARSER_TYPE_TA 32768
  88
  89 /**
  90  * A DNS query.
  91  */
  92 struct GNUNET_DNSPARSER_Query
  93 {
  94
  95   /**
  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.
 101    */
 102   char *name;
 103
 104   /**
 105    * See GNUNET_DNSPARSER_TYPE_*.
 106    */
 107   uint16_t type;
 108
 109   /**
 110    * See GNUNET_TUN_DNS_CLASS_*.
 111    */
 112   uint16_t dns_traffic_class;
 113
 114 };
 115
 116
 117 /**
 118  * Information from MX records (RFC 1035).
 119  */
 120 struct GNUNET_DNSPARSER_MxRecord
 121 {
 122
 123   /**
 124    * Preference for this entry (lower value is higher preference).
 125    */
 126   uint16_t preference;
 127
 128   /**
 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.
 134    */
 135   char *mxhost;
 136
 137 };
 138
 139
 140 /**
 141  * Information from SRV records (RFC 2782).
 142  */
 143 struct GNUNET_DNSPARSER_SrvRecord
 144 {
 145
 146   /**
 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.
 152    */
 153   char *target;
 154
 155   /**
 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.
 159    */
 160   uint16_t priority;
 161
 162   /**
 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.
 166    */
 167   uint16_t weight;
 168
 169   /**
 170    * TCP or UDP port of the service.
 171    */
 172   uint16_t port;
 173
 174 };
 175
 176
 177 /**
 178  * DNS CERT types as defined in RFC 4398.
 179  */
 180 enum GNUNET_DNSPARSER_CertType
 181 {
 182   /**
 183    *  Reserved value
 184    */
 185   GNUNET_DNSPARSER_CERTTYPE_RESERVED = 0,
 186
 187   /**
 188    * An x509 PKIX certificate
 189    */
 190   GNUNET_DNSPARSER_CERTTYPE_PKIX = 1,
 191
 192   /**
 193    * A SKPI certificate
 194    */
 195   GNUNET_DNSPARSER_CERTTYPE_SKPI = 2,
 196
 197   /**
 198    * A PGP certificate
 199    */
 200   GNUNET_DNSPARSER_CERTTYPE_PGP = 3,
 201
 202   /**
 203    * An x509 PKIX cert URL
 204    */
 205   GNUNET_DNSPARSER_CERTTYPE_IPKIX = 4,
 206
 207   /**
 208    * A SKPI cert URL
 209    */
 210   GNUNET_DNSPARSER_CERTTYPE_ISKPI = 5,
 211
 212   /**
 213    * A PGP cert fingerprint and URL
 214    */
 215   GNUNET_DNSPARSER_CERTTYPE_IPGP = 6,
 216
 217   /**
 218    * An attribute Certificate
 219    */
 220   GNUNET_DNSPARSER_CERTTYPE_ACPKIX = 7,
 221
 222   /**
 223    * An attribute cert URL
 224    */
 225   GNUNET_DNSPARSER_CERTTYPE_IACKPIX = 8
 226 };
 227
 228
 229 /**
 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
 232  */
 233 enum GNUNET_DNSPARSER_CertAlgorithm
 234 {
 235   /**
 236    * No defined
 237    */
 238   GNUNET_DNSPARSER_CERTALGO_UNDEFINED = 0,
 239
 240   /**
 241    * RSA/MD5
 242    */
 243   GNUNET_DNSPARSER_CERTALGO_RSAMD5 = 1,
 244
 245   /**
 246    * Diffie-Hellman
 247    */
 248   GNUNET_DNSPARSER_CERTALGO_DH = 2,
 249
 250   /**
 251    * DSA/SHA1
 252    */
 253   GNUNET_DNSPARSER_CERTALGO_DSASHA = 3,
 254
 255   /**
 256    * Reserved
 257    */
 258   GNUNET_DNSPARSER_CERTALGO_RSRVD4 = 4,
 259
 260   /**
 261    * RSA/SHA1
 262    */
 263   GNUNET_DNSPARSER_CERTALGO_RSASHA = 5,
 264
 265   /**
 266    * DSA/NSEC3/SHA
 267    */
 268   GNUNET_DNSPARSER_CERTALGO_DSANSEC3 = 6,
 269
 270   /**
 271    * RSA/NSEC3/SHA
 272    */
 273   GNUNET_DNSPARSER_CERTALGO_RSANSEC3 = 7,
 274
 275   /**
 276    * RSA/SHA256
 277    */
 278   GNUNET_DNSPARSER_CERTALGO_RSASHA256 = 8,
 279
 280   /**
 281    * Reserved
 282    */
 283   GNUNET_DNSPARSER_CERTALGO_RSRVD9 = 9,
 284
 285   /**
 286    * RSA/SHA512
 287    */
 288   GNUNET_DNSPARSER_CERTALGO_RSASHA512 = 10,
 289
 290   /**
 291    * GOST R 34.10-2001
 292    */
 293   GNUNET_DNSPARSER_CERTALGO_GOST_R34 = 12,
 294
 295   /**
 296    * ECDSA Curve P-256/SHA256
 297    */
 298   GNUNET_DNSPARSER_CERTALGO_ECDSA_P256SHA256 = 13,
 299
 300   /**
 301    * ECDSA Curve P-384/SHA384
 302    */
 303   GNUNET_DNSPARSER_CERTALGO_ECDSA_P384SHA384 = 14
 304
 305 };
 306
 307
 308 /**
 309  * Information from CERT records (RFC 4034).
 310  */
 311 struct GNUNET_DNSPARSER_CertRecord
 312 {
 313
 314   /**
 315    * Certificate type
 316    */
 317   enum GNUNET_DNSPARSER_CertType cert_type;
 318
 319   /**
 320    * Certificate KeyTag
 321    */
 322   uint16_t cert_tag;
 323
 324   /**
 325    * Algorithm
 326    */
 327   enum GNUNET_DNSPARSER_CertAlgorithm algorithm;
 328
 329   /**
 330    * Number of bytes in @e certificate_data
 331    */
 332   size_t certificate_size;
 333
 334   /**
 335    * Data of the certificate.
 336    */
 337   char *certificate_data;
 338
 339 };
 340
 341
 342 /**
 343  * Information from SOA records (RFC 1035).
 344  */
 345 struct GNUNET_DNSPARSER_SoaRecord
 346 {
 347
 348   /**
 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.
 355    */
 356   char *mname;
 357
 358   /**
 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.
 365    */
 366   char *rname;
 367
 368   /**
 369    * The version number of the original copy of the zone.
 370    */
 371   uint32_t serial;
 372
 373   /**
 374    * Time interval before the zone should be refreshed.
 375    */
 376   uint32_t refresh;
 377
 378   /**
 379    * Time interval that should elapse before a failed refresh should
 380    * be retried.
 381    */
 382   uint32_t retry;
 383
 384   /**
 385    * Time value that specifies the upper limit on the time interval
 386    * that can elapse before the zone is no longer authoritative.
 387    */
 388   uint32_t expire;
 389
 390   /**
 391    * The bit minimum TTL field that should be exported with any RR
 392    * from this zone.
 393    */
 394   uint32_t minimum_ttl;
 395
 396 };
 397
 398
 399 /**
 400  * Binary record information (unparsed).
 401  */
 402 struct GNUNET_DNSPARSER_RawRecord
 403 {
 404
 405   /**
 406    * Binary record data.
 407    */
 408   void *data;
 409
 410   /**
 411    * Number of bytes in data.
 412    */
 413   size_t data_len;
 414 };
 415
 416
 417 /**
 418  * A DNS response record.
 419  */
 420 struct GNUNET_DNSPARSER_Record
 421 {
 422
 423   /**
 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.
 429    */
 430   char *name;
 431
 432   /**
 433    * Payload of the record (which one of these is valid depends on the 'type').
 434    */
 435   union
 436   {
 437
 438     /**
 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.
 444      */
 445     char *hostname;
 446
 447     /**
 448      * SOA data for SOA records.
 449      */
 450     struct GNUNET_DNSPARSER_SoaRecord *soa;
 451
 452     /**
 453      * CERT data for CERT records.
 454      */
 455     struct GNUNET_DNSPARSER_CertRecord *cert;
 456
 457     /**
 458      * MX data for MX records.
 459      */
 460     struct GNUNET_DNSPARSER_MxRecord *mx;
 461
 462     /**
 463      * SRV data for SRV records.
 464      */
 465     struct GNUNET_DNSPARSER_SrvRecord *srv;
 466
 467     /**
 468      * Raw data for all other types.
 469      */
 470     struct GNUNET_DNSPARSER_RawRecord raw;
 471
 472   } data;
 473
 474
 475   /**
 476    * When does the record expire?
 477    */
 478   struct GNUNET_TIME_Absolute expiration_time;
 479
 480   /**
 481    * See GNUNET_DNSPARSER_TYPE_*.
 482    */
 483   uint16_t type;
 484
 485   /**
 486    * See GNUNET_TUN_DNS_CLASS_*.
 487    */
 488   uint16_t dns_traffic_class;
 489
 490 };
 491
 492
 493 /**
 494  * Easy-to-process, parsed version of a DNS packet.
 495  */
 496 struct GNUNET_DNSPARSER_Packet
 497 {
 498   /**
 499    * Array of all queries in the packet, must contain "num_queries" entries.
 500    */
 501   struct GNUNET_DNSPARSER_Query *queries;
 502
 503   /**
 504    * Array of all answers in the packet, must contain "num_answers" entries.
 505    */
 506   struct GNUNET_DNSPARSER_Record *answers;
 507
 508   /**
 509    * Array of all authority records in the packet, must contain "num_authority_records" entries.
 510    */
 511   struct GNUNET_DNSPARSER_Record *authority_records;
 512
 513   /**
 514    * Array of all additional answers in the packet, must contain "num_additional_records" entries.
 515    */
 516   struct GNUNET_DNSPARSER_Record *additional_records;
 517
 518   /**
 519    * Number of queries in the packet.
 520    */
 521   unsigned int num_queries;
 522
 523   /**
 524    * Number of answers in the packet, should be 0 for queries.
 525    */
 526   unsigned int num_answers;
 527
 528   /**
 529    * Number of authoritative answers in the packet, should be 0 for queries.
 530    */
 531   unsigned int num_authority_records;
 532
 533   /**
 534    * Number of additional records in the packet, should be 0 for queries.
 535    */
 536   unsigned int num_additional_records;
 537
 538   /**
 539    * Bitfield of DNS flags.
 540    */
 541   struct GNUNET_TUN_DnsFlags flags;
 542
 543   /**
 544    * DNS ID (to match replies to requests).
 545    */
 546   uint16_t id;
 547
 548 };
 549
 550
 551 /**
 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.
 554  *
 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
 558  */
 559 int
 560 GNUNET_DNSPARSER_check_label (const char *label);
 561
 562
 563 /**
 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.
 567  *
 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
 571  */
 572 int
 573 GNUNET_DNSPARSER_check_name (const char *name);
 574
 575
 576 /**
 577  * Parse a UDP payload of a DNS packet in to a nice struct for further
 578  * processing and manipulation.
 579  *
 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
 583  */
 584 struct GNUNET_DNSPARSER_Packet *
 585 GNUNET_DNSPARSER_parse (const char *udp_payload,
 586                         size_t udp_payload_length);
 587
 588
 589 /**
 590  * Free memory taken by a packet.
 591  *
 592  * @param p packet to free
 593  */
 594 void
 595 GNUNET_DNSPARSER_free_packet (struct GNUNET_DNSPARSER_Packet *p);
 596
 597
 598 /**
 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.
 603  *
 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
 611  */
 612 int
 613 GNUNET_DNSPARSER_pack (const struct GNUNET_DNSPARSER_Packet *p,
 614                        uint16_t max,
 615                        char **buf,
 616                        size_t *buf_length);
 617
 618 /* ***************** low-level packing API ******************** */
 619
 620 /**
 621  * Add a DNS name to the UDP packet at the given location, converting
 622  * the name to IDNA notation as necessary.
 623  *
 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
 632  */
 633 int
 634 GNUNET_DNSPARSER_builder_add_name (char *dst,
 635                                    size_t dst_len,
 636                                    size_t *off,
 637                                    const char *name);
 638
 639
 640 /**
 641  * Add a DNS query to the UDP packet at the given location.
 642  *
 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
 651  */
 652 int
 653 GNUNET_DNSPARSER_builder_add_query (char *dst,
 654                                     size_t dst_len,
 655                                     size_t *off,
 656                                     const struct GNUNET_DNSPARSER_Query *query);
 657
 658
 659 /**
 660  * Add an MX record to the UDP packet at the given location.
 661  *
 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
 670  */
 671 int
 672 GNUNET_DNSPARSER_builder_add_mx (char *dst,
 673                                  size_t dst_len,
 674                                  size_t *off,
 675                                  const struct GNUNET_DNSPARSER_MxRecord *mx);
 676
 677
 678 /**
 679  * Add an SOA record to the UDP packet at the given location.
 680  *
 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
 689  */
 690 int
 691 GNUNET_DNSPARSER_builder_add_soa (char *dst,
 692                                   size_t dst_len,
 693                                   size_t *off,
 694                                   const struct GNUNET_DNSPARSER_SoaRecord *soa);
 695
 696
 697 /**
 698  * Add CERT record to the UDP packet at the given location.
 699  *
 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
 708  */
 709 int
 710 GNUNET_DNSPARSER_builder_add_cert (char *dst,
 711                                    size_t dst_len,
 712                                    size_t *off,
 713                                    const struct GNUNET_DNSPARSER_CertRecord *cert);
 714
 715
 716 /**
 717  * Add an SRV record to the UDP packet at the given location.
 718  *
 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
 727  */
 728 int
 729 GNUNET_DNSPARSER_builder_add_srv (char *dst,
 730                                   size_t dst_len,
 731                                   size_t *off,
 732                                   const struct GNUNET_DNSPARSER_SrvRecord *srv);
 733
 734 /* ***************** low-level parsing API ******************** */
 735
 736 /**
 737  * Parse a DNS record entry.
 738  *
 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
 745  */
 746 int
 747 GNUNET_DNSPARSER_parse_record (const char *udp_payload,
 748                                size_t udp_payload_length,
 749                                size_t *off,
 750                                struct GNUNET_DNSPARSER_Record *r);
 751
 752
 753 /**
 754  * Parse name inside of a DNS query or record.
 755  *
 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
 761  */
 762 char *
 763 GNUNET_DNSPARSER_parse_name (const char *udp_payload,
 764                              size_t udp_payload_length,
 765                              size_t *off);
 766
 767
 768 /**
 769  * Parse a DNS query entry.
 770  *
 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
 777  */
 778 int
 779 GNUNET_DNSPARSER_parse_query (const char *udp_payload,
 780                               size_t udp_payload_length,
 781                               size_t *off,
 782                               struct GNUNET_DNSPARSER_Query *q);
 783
 784
 785 /**
 786  * Parse a DNS SOA record.
 787  *
 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
 793  */
 794 struct GNUNET_DNSPARSER_SoaRecord *
 795 GNUNET_DNSPARSER_parse_soa (const char *udp_payload,
 796                             size_t udp_payload_length,
 797                             size_t *off);
 798
 799
 800 /**
 801  * Parse a DNS CERT record.
 802  *
 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
 808  */
 809 struct GNUNET_DNSPARSER_CertRecord *
 810 GNUNET_DNSPARSER_parse_cert (const char *udp_payload,
 811                              size_t udp_payload_length,
 812                              size_t *off);
 813
 814
 815 /**
 816  * Parse a DNS MX record.
 817  *
 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
 823  */
 824 struct GNUNET_DNSPARSER_MxRecord *
 825 GNUNET_DNSPARSER_parse_mx (const char *udp_payload,
 826                            size_t udp_payload_length,
 827                            size_t *off);
 828
 829
 830 /**
 831  * Parse a DNS SRV record.
 832  *
 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
 838  */
 839 struct GNUNET_DNSPARSER_SrvRecord *
 840 GNUNET_DNSPARSER_parse_srv (const char *udp_payload,
 841                             size_t udp_payload_length,
 842                             size_t *off);
 843
 844 /* ***************** low-level deallocation API ******************** */
 845
 846 /**
 847  * Free the given DNS record.
 848  *
 849  * @param r record to free
 850  */
 851 void
 852 GNUNET_DNSPARSER_free_record (struct GNUNET_DNSPARSER_Record *r);
 853
 854
 855 /**
 856  * Free MX information record.
 857  *
 858  * @param mx record to free
 859  */
 860 void
 861 GNUNET_DNSPARSER_free_mx (struct GNUNET_DNSPARSER_MxRecord *mx);
 862
 863
 864 /**
 865  * Free SRV information record.
 866  *
 867  * @param srv record to free
 868  */
 869 void
 870 GNUNET_DNSPARSER_free_srv (struct GNUNET_DNSPARSER_SrvRecord *srv);
 871
 872
 873 /**
 874  * Free SOA information record.
 875  *
 876  * @param soa record to free
 877  */
 878 void
 879 GNUNET_DNSPARSER_free_soa (struct GNUNET_DNSPARSER_SoaRecord *soa);
 880
 881
 882 /**
 883  * Free CERT information record.
 884  *
 885  * @param cert record to free
 886  */
 887 void
 888 GNUNET_DNSPARSER_free_cert (struct GNUNET_DNSPARSER_CertRecord *cert);
 889
 890
 891 /**
 892  * Convert a block of binary data to HEX.
 893  *
 894  * @param data binary data to convert
 895  * @param data_size number of bytes in @a data
 896  * @return HEX string (lower case)
 897  */
 898 char *
 899 GNUNET_DNSPARSER_bin_to_hex (const void *data,
 900                              size_t data_size);
 901
 902
 903 /**
 904  * Convert a HEX string to block of binary data.
 905  *
 906  * @param hex HEX string to convert (may contain mixed case)
 907  * @param data where to write result, must be
 908  *             at least `strlen(hex)/2` bytes long
 909  * @return number of bytes written to data
 910  */
 911 size_t
 912 GNUNET_DNSPARSER_hex_to_bin (const char *hex,
 913                              void *data);
 914
 915
 916 #endif
 917
 918 /** @} */  /* end of group */