<?xml version="1.0"?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<!-- $Id -->

<?rfc toc="yes" ?>
<?rfc compact="yes" ?>
<?rfc editing="no" ?>
<?rfc iprnotified="no" ?>
<?rfc private="LibDNS API" ?>

<rfc ipr="none" category="info" docName="libdns-api-00.txt">

<front>
<title>LibDNS API</title>
    <author initials="R." surname="Gieben" fullname="Miek Gieben">
     <organization>NLnet Labs</organization>
      <address>
        <postal>
          <street>Kruislaan 419</street>
          <city>Amsterdam</city>
          <code>1098 VA</code>
          <country>The Netherlands</country>
        </postal>
        <email>miek@nlnetlabs.nl</email>
        <uri>http://www.nlnetlabs.nl</uri>
      </address>
    </author>
    <author initials="J." surname="Jansen" fullname="Jelte Jansen">
     <organization>NLnet Labs</organization>
      <address>
        <postal>
          <street>Kruislaan 419</street>
          <city>Amsterdam</city>
          <code>1098 VA</code>
          <country>The Netherlands</country>
        </postal>
        <email>jelte@nlnetlabs.nl</email>
        <uri>http://www.nlnetlabs.nl</uri>
      </address>
    </author>
    <author initials="E." surname="Rozendaal" fullname="Erik Rozendaal">
     <organization>NLnet Labs</organization>
      <address>
        <postal>
          <street>Kruislaan 419</street>
          <city>Amsterdam</city>
          <code>1098 VA</code>
          <country>The Netherlands</country>
        </postal>
        <email>erik@nlnetlabs.nl</email>
        <uri>http://www.nlnetlabs.nl</uri>
      </address>
    </author>
<date month="January" year="2005" />
<keyword>DNS</keyword>
<keyword>Elite</keyword>
<keyword>Hacking</keyword>
<abstract>
<t>
A small abstract will come here, TBD.
</t>
</abstract>
</front>

<middle>

<section title="Introduction">
<t>
LibDNS (or lDNS) is modelled after the Net::DNS perl library. It has
been shown that Net::DNS  can be used efficiently for
programming DNS aware applications. We want to bring the same
level of efficiency to C programmers.
</t>
<t>
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.
</t>
</section> <!-- "Introduction" -->

<section title="Differences With Other Libraries">
<t>
Short intermezzo detailing differences with other libraries. Most important
ones are the libc resolver interface (from BIND8) and the lwres_ interface
from BIND9.
</t>
</section> <!-- "Differences with other libraries" -->

<section title="Interfaces">
<t>
At its lowest level lDNS  is only dependent on libc. It uses a 
few networking systems calls; socket, bind, send/recv and friends.
</t>
<t>
Further more it is to be expected that lDNS will depend on OpenSSL for
its cryptography.
</t>
<t>
As said, lDNS is modelled after Net::DNS, therefore its application API
looks very much like the one used for Net::DNS. Some modification are made
of course, because not all functionality of Perl can be caught in C.
</t>

<t>
This API document was written by carefully looking at the documentation
contained in the Net::DNS Perl module.
</t>
</section> <!-- "Interfaces" -->

<section title="RDF Structure">
<t>
The rdf structure, the RData Field, is a type that contains the different 
types in the rdata of an RR. Consider the following example:
<artwork>
example.com.	IN	MX	10 mx.example.com.
</artwork>
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.
</t>
<t>
The following functions operate on this structure.
</t>
<t>
<list style="hanging">
<t hangText="dns_rdf *ldns_rdf_new(uint16_t s, ldns_rdf_type t, uint8_t *d):">
Create a new rdf structure. Return a pointer to it.
</t>
<t hangText="uint16_t ldns_rdf_size(ldns_rdf *r):">
Get the size of a rdf structure.
</t>
<t hangText="void ldns_rdf_set_size(ldns_rdf *r, uint16_t):">
Set the size of a rdf structure.
</t>
<t hangText="void ldns_rdf_set_type(ldns_rdf *r, ldns_rdf_type t):">
Set the type of a rdf structure.
</t>
<t hangText="ldns_rdf_type ldns_rdf_get_type(ldns_rdf *r):">
Get the type of a rdf structure.
</t>
<t hangText="void ldns_rdf_set_data(ldns_rdf *r, uint8_t *n):">
Set the (binary/network order) data of a rdf structure.
</t>
<t hangText="uint8_t *ldns_rdf_data(ldns_rdf *r):">
Get a pointer to the data in a rdf structure.
</t>
<t hangText="void ldns_rdf_free(ldns_rdf *r):">
Free a rdf structure.
</t>
<t hangText="ldns_rdf_new_frm_str(uint8_t *s, ldns_rdf_type t):">
Create a new rdf structure from a string and a specific rdf_type.
The type is needed to perform the correct conversion.
</t>
</list>
</t>
</section> <!-- "RDF Structure" -->

<section title="RR Structure">
<t>
These functions operate on ldns_rr structures.
</t>
<t>
<list style="hanging">
<t hangText="ldns_rr *ldns_rr_new(void):">
Returns a pointer to the newly created ldns_rr structure.
</t>
<t hangText="void ldns_rr_print(FILE *s, ldns_rr *r):">
Prints the record to the stream s.
</t>
<t hangText="ldns_buffer ldns_rr_rdatastr(ldns_rr *r):">
Returns a pointer to a ldns_buffer containing with string containing
RR-specific data.
</t>
<t hangText="ldns_rdf *ldns_rr_name(ldns_rr *r):">
Returns the record's owner name as a ldns_rdf type. 
</t>
<t hangText="ldns_rdf_rr_type ldns_rr_get_type(ldns_rr *r):">
Returns the record's type.
</t>
<t hangText="ldns_rr_class ldns_rr_get_class(ldns_rr *r):">
Returns the record's class.
</t>
<t hangText="uint32_t ldns_rr_get_ttl(ldns_rr *r):">
Returns the record's time-to-live (TTL).
</t>
</list>
</t>

<t>
TODO the 'set' functions of the 'get'
</t>
</section> <!-- "RR Structure" -->

<section title="RR list Structure">
<t>
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 separate object.
</t>
<t>
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.
</t>
<t>
TODO:  See rr.c
</t>
</section> <!-- "RR list Structure" -->

<section title="Resolver Structure">
<t>
<list style="hanging">
<t hangText="ldns_resolver* ldns_resolver_new(void):">
Create a new resolver structure and return the pointer to that.
</t>
<t hangText="uint8_t ldns_version(resolver *res):">
Returns the version of lDNS.
</t>
<t hangText="ldns_pkt *ldns_mx(ldns_resolver *res, ldns_rdf_type *dname):">
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
</t>
<t hangText="ldns_status ldns_resolver_domain(resolver *res, ldns_rdf
*domain):">
 Set the default domain for this resolver. This domain is added
     when a query is made with a name without a trailing dot.

     
</t>
<t hangText="ldns_status ldns_resolver_nameserver_push(resolver *res,
ldns_rdf *ip):">
Add a new nameserver to the resolver. These nameservers are queried
    when a search() or query() is done.
    
</t>
<t hangText="ldns_status ldns_resolver_searchlist_push(resolver *res,
ldns_rdf *domain):">
 Add a domain to the searchlist of a resolver.
</t>
<t hangText=" ldns_pkt * ldns_resolver_search(ldns_resolver *res,
                                ldns_rdf *domain,
                                ldns_rr_type *type,
                                ldns_class *class):">
 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'.
</t>
<t hangText="ldns_pkt * ldns_resolver_query(ldns_resolver *res,
                                 ldns_rdf *dom,
                                 ldns_type *t,
                                 ldns_class *cl):">
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'.
</t>
<t hangText=" ldns_pkt * ldns_resolver_send(ldns_resolver *res,
                                ldns_rdf *domain,
                                ldns_type *type,
                                ldns_class *class):">
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'.
</t>
</list>
</t>
<t>
TODO XX Gazillion  helper functions to set port, src-port, etc. etc.
</t>
</section> <!-- "Resolver Structure" -->

<section title="Packet Structure">
<t>
A packet structure (ldns_pkt) has five sections:
<list style="numbers">
<t>The header section, a ldns_hdr structure.</t>
<t>The question section, a ldns_rr_list structure.</t>
<t>The answer section, a ldns_rr_list structure.</t>
<t>The authority section, a ldns_rr_list structure.</t>
<t>The additional section, a ldns_rr_list structure.</t>
</list>
</t>
<t>
<list style="hanging">
<t hangText="Header Structure (ldns_hdr):">
ldns_hdr represents the header section of a DNS packet.
</t>
<t hangText="Question Section (ldns_rr_list):">
A list of RRs in the Question section of a DNS packet.
</t>
<t hangText="Answer Section (ldns_rr_list):">
A list of RRs in the Question section of a DNS packet.                     
</t>                             
<t hangText="Authority Section (ldns_rr_list):">
A list of RRs in the Question section of a DNS packet.
</t> 
<t hangText="Additional Section (ldns_rr_list):"> 
A list of RRs in the Question section of a DNS packet.                      
</t> 
</list>
</t>

<t>
<list style="hanging">
<t hangText="ldns_pkt * ldns_pkt_new(void):">
Creates a new empty packet.
</t>
<t hangText="ldns_buffer* ldns_pkt_data(ldns_pkt *pkt):">
Returns the packet data in binary format, suitable for sending to a
nameserver. [XXX, suitable for sending to a NS?]
</t>
<t hangText="ldns_hdr *ldns_header(ldn_pkt *pkt):">
Returns a ldns_hdr structure representing the header section of
the packet.
</t>
<t hangText="ldns_rr_list *ldns_question(ldns_pkt *pkt):">
 Returns a pointer to a ldns_rr_list representing the question section
of the packet.
</t>
<t hangText="ldns_rr_list *ldns_answer(ldns_pkt *pkt):">
 Returns a pointer to a ldns_rr_list representing the answer section of
the packet.
     
</t>
<t hangText=" ldns_rr_list *ldns_authority(ldns_pkt *pkt):">
Returns a pointer to a ldns_rr_list representing the authority section
of the packet.
    
</t>
<t hangText=" ldns_rr_list *ldns_additional(ldns_pkt *pkt):">
Returns a pointer to a ldns_rr_list of representing the additional
section of the packet.
	
</t>
<t hangText=" void ldns_pkt_print(ldns_pkt *pkt):">
Prints the packet data on the standard output in an ASCII format similar
to that used in DNS zone files. See RFC1035.
      
</t>
<t hangText="ldns_buffer *ldns_pkt_string(ldns_pkt *pkt):">
Returns a ldns_buffer containing the string representation of the packet.
 
</t>
<t hangText="ldns_rdf* ldns_pkt_answerfrom(ldns_pkt *pkt):">
Returns the IP address from which we received this packet. User-created
packets will return NULL.
     
</t>
<t hangText="uint16_t ldns_pkt_answersize(ldns_pkt *pkt):">
Returns the size of the packet in bytes as it was received from a
nameserver. User-created packets will return 0. [XXX
user-created??]
	
</t>
<t hangText="ldns_status ldns_push(ldns_pkt *pkt, ldns_pkt_section section,
ldns_rr *rr):">
Adds *rr to the specified section of the packet. Return LDNS_STATUS_OK
on success, LDNS_STATUS_ERR otherwise.
      
</t>
<t hangText="ldns_status ldns_unique_push(ldns_pkt *pkt, ldns_pkt_section
section, ldns_rr *rr):">
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.
</t>
<t hangText="ldns_rr *ldns_pop(ldns_pkt, ldns_pkt_section):">
Removes a RR from the specified section of the packet. Returns NULL if
no RR's could be popped.
</t>
<t hangText="ldns_rr_list *ldns_pkt_rrset(ldns_pkt *pkt,...):">
Retrieve all RRs in a packet matching certain criteria. XXX function needs
to be specified better.
</t>
<t hangText="void *ldns_pkt_print(FILE *s, ldns_pkt *p):">
Print packet p to stream s.
</t>

</list>
</t>
</section> <!-- "Packet Structure" -->

<section title="Specific RR Structures">
<t>
Some resource records can have special access function no other RR has.
Those are detailed here. XXX TODO don't exist (yet?).
</t>
</section> <!-- "Specific RR Structures" -->

<section title="Exported Defines and Macros">
<t>
insert your long list here.
</t>
</section> <!-- "Exported defines and macros" -->

<section title="Examples">
<t>
A small example, which queries a nameserver on localhost
to display the MX records for miek.nl.
</t>

<t>
<figure>
<artwork>
/**
 * An example ldns program
 * In semi-C code
 *
 * Setup a resolver
 * Query a nameserver
 * Print the result
 */

#include &lt;ldns.h&gt;

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;
}
</artwork>
</figure>
</t>
</section> <!-- title="Short Example" -->

</middle>  
<back>
</back>
</rfc>