# LibDNS API

NLnet Labs

              Kruislaan 419
              Amsterdam
              1098 VA
              The Netherlands

            miek@nlnetlabs.nl
            http://www.nlnetlabs.nl

NLnet Labs

              Kruislaan 419
              Amsterdam
              1098 VA
              The Netherlands

            jelte@nlnetlabs.nl
            http://www.nlnetlabs.nl

NLnet Labs

              Kruislaan 419
              Amsterdam
              1098 VA
              The Netherlands

            erik@nlnetlabs.nl
            http://www.nlnetlabs.nl

DNS
Elite
Hacking

A small abstract will come here, TBD.

# Introduction

LibDNS (or lDNS) is modelled after the Net::DNS perl library. It has been shown that Net::DNS can be used vefficiently for programming DNS aware applications. We want to bring the same level of efficiency to C programmers.
The lDNS API consist of two layers. The top-layer, this is what is actually exported to the application via the library. And the bottom-layer, this is what lDNS needs to compile and function.

# Differences With Other Libraries

Short intermezzo detailing differences with other libraries. Most important ones are the libc resolver interface (from BIND8) and the lwres_ interface from BIND9.

# Interfaces

At its lowest level lDNS is only dependent on libc. It uses a few networking systems calls; socket, bind, send/recv and friends.
Further more it is to be expected that lDNS will depend on OpenSSL for its cryptography.
As said, lDNS is modelled after Net::DNS, therefor its application API looks very much like the one used for Net::DNS. Some modification are made ofcourse, because not all functionality of Perl can be caught in C.
This API document was written by carefully looking at the documentation contained in the Net::DNS Perl module.

# RDF Structure

The rdf structure, the RData Field, is a type that contains the different types in the rdata of an RR. Consider the following example: example.com. IN MX 10 mx.example.com. The "10 mx.example.com." is the rdata in this case. It consists of two fields, "10" and "mx.example.com". These have the types (in this case) LDNS_RDF_TYPE_INT8 and LDNS_RDF_TYPE_DNAME.
The following functions operate on this structure.
Create a new rdf structure. Return a pointer to it.
Get the size of a rdf structure.
Set the size of a rdf structure.
Set the type of a rdf structure.
Get the type of a rdf structure.
Set the (binary/network order) data of a rdf structure.
Get a pointer to the data in a rdf structure.
Free a rdf structure.
Create a new rdf structure from a string and a specific rdf_type. The type is needed to perform the correct conversion.

# RR Structure

These functions operate on ldns_rr structures.
Returns a pointer to the newly created ldns_rr structure.
Prints the record to the stream s.
Returns a pointer to a ldns_buffer containing with string containing RR-specific data.
Returns the record's owner name as a ldns_rdf type.
Returns the record's type.
Returns the record's class.
Returns the record's time-to-live (TTL).
TODO the 'set' functions of the 'get'

# RR list Structure

In the DNS the atomic data type is an RRset. This is a list of RRs with the same ownername, type and class. Net::DNS doesn't have rrsets as a seperate object.
In lDNS we have the ldns_rr_list, which just holds a bunch of RR's. No specific check are made on the RRs that can be put in such a list. Special wrapper functions exist which allow the usage of ldns_rr_list of real (RFC compliant) RR sets.
TODO: See rr.c

# Resolver Structure

Create a new resolver structure and return the pointer to that.
Returns the version of lDNS.
Returns a ldns_pkt representing the MX records for the specified dname. Function is documented differently in Net::DNS. Do we need stuff like this?? XXX
Set the default domain for this resolver. This domain is added when a query is made with a name without a trailing dot.

Add a new nameserver to the resolver. These nameservers are queried when a search() or query() is done.

Add a domain to the searchlist of a resolver.
Perform a query. Try all the nameservers in the *res structure. Apply the search list. And default domain. If type is NULL it defaults to 'A', If class is NULL it default to 'IN'.
Perform a query. Only the default domain is added. If type is NULL it defaults to 'A', If class is NULL it default to 'IN'.
No search list nor default domain is applied. Return a pointer to a ldns_pkt structure with the information from the nameserver. If type is NULL it defaults to 'A', If class is NULL it default to 'IN'.
TODO XX Gazillion helper functions to set port, src-port, etc. etc.

# Packet Structure

A packet structure (ldns_pkt) has five sections: The header section, a ldns_hdr structure. The question section, a ldns_rr_list structure. The answer section, a ldns_rr_list structure. The authority section, a ldns_rr_list structure. The additional section, a ldns_rr_list structure.
ldns_hdr represents the header section of a DNS packet.
A list of RRs in the Question section of a DNS packet.
A list of RRs in the Question section of a DNS packet.
A list of RRs in the Question section of a DNS packet.
A list of RRs in the Question section of a DNS packet.
Creates a new empty packet.
Returns the packet data in binary format, suitable for sending to a nameserver. [XXX, suitable for sending to a NS?]
Returns a ldns_hdr structure representing the header section of the packet.
Returns a pointer to a ldns_rr_list representing the question section of the packet.
Returns a pointer to a ldns_rr_list representing the answer section of the packet.

Returns a pointer to a ldns_rr_list representing the authority section of the packet.

Returns a pointer to a ldns_rr_list of representing the additional section of the packet.

Prints the packet data on the standard output in an ASCII format similar to that used in DNS zone files. See RFC1035.

Returns a ldns_buffer containing the string representation of the packet.

Returns the IP address from which we received this packet. User-created packets will return NULL.

Returns the size of the packet in bytes as it was received from a nameserver. User-created packets will return 0. [XXX user-created??]

Adds *rr to the specified section of the packet. Return LDNS_STATUS_OK on success, LDNS_STATUS_ERR otherwise.

Adds *rr to the specified section of the packet provided that the RR does not already exist in the packet. Return LDNS_STATUS_OK on success, LDNS_STATUS_ERR otherwise.
Removes a RR from the specified section of the packet. Returns NULL if no RR's could be popped.
Retrieve all RRs in a packet matching certain criteria. XXX function needs to be specified better.
Print packet p to stream s.

# Specific RR Structures

Some resource records can have special access function no other RR has. Those are detailed here. XXX TODO don't exist (yet?).

# Exported Defines and Macros

insert your long list here.

# Examples

A small example, which queries a nameserver on localhost to diplay the MX records for miek.nl.
/** * An example ldns program * In semi-C code * * Setup a resolver * Query a nameserver * Print the result */

#include <ldns.h>

int main(void) { ldns_resolver *res; ldns_rdf *default_dom; ldns_rdf *nameserver; ldns_rdf *qname; ldns_pkt *pkt;

/* init */ res = ldns_resolver_new(); if (!res) return 1;

/* create a default domain and add it */ default_dom = ldns_rdf_new_frm_str("miek.nl.", LDNS_RDF_TYPE_DNAME); nameserver = ldns_rdf_new_frm_str("127.0.0.1", LDNS_RDF_TYPE_A);

if (ldns_resolver_domain(res, default_dom) != LDNS_STATUS_OK) return 1; if (ldns_resolver_nameserver_push(res, nameserver) != LDNS_STATUS_OK) return 1;

/* setup the question */ qname = ldns_rdf_new_frm_str("www", LDNS_RDF_TYPE_DNAME);

/* fire it off. "miek.nl." will be added */ pkt = ldns_resolver_query(res, qname, LDNS_RR_TYPE_MX, NULL);

/* print the resulting pkt to stdout */ ldns_pkt_print(stdout, pkt);

return 0; }