LibDNS APINLnet LabsKruislaan 419Amsterdam1098 VAThe Netherlandsmiek@nlnetlabs.nlhttp://www.nlnetlabs.nlNLnet LabsKruislaan 419Amsterdam1098 VAThe Netherlandsjelte@nlnetlabs.nlhttp://www.nlnetlabs.nlNLnet LabsKruislaan 419Amsterdam1098 VAThe Netherlandserik@nlnetlabs.nlhttp://www.nlnetlabs.nlDNSEliteHacking
A small abstract will come here, TBD.
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.
Short intermezzo detailing differences with other libraries. Most important
ones are the libc resolver interface (from BIND8) and the lwres_ interface
from BIND9.
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.
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.
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'
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
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.
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.
Some resource records can have special access function no other RR has.
Those are detailed here. XXX TODO don't exist (yet?).
insert your long list here.
A small example, which queries a nameserver on localhost
to diplay the MX records for miek.nl.