ldns - Overview document

1. Introduction


1.1 Global decisions
  o IP4/6 agnostic - only the resolver at is lowest level will handle/see
    this. (there will be an option to force 4 or 6)
  o Keep an eye on the Windows network API for portability issues. 
  o Compression happens only in the WIRE module. Compressible RRs
    are known by the library.
  o It is possible to directly communicate with the network module,
    thereby bypassing the resolver. For simple application going through
    the Resolver module is preferred.
  o All modules will export functions to client applications.
  o All the stuff from the network is put in ldns_buffer's by 
    the network module. All binary data coming from the network
    module is encapsulated in the ldns_XX types.
  o DNSSEC crypto is handled in a seperate module, where
    for instance sign(key, rrlist, **sig) and verify(key, rrlist, sig)
    will be defined.
  o DNSSEC is optional as it depends on OpenSSL
  o IF and rdf is LDNS_RDF_TYPE_DNAME then the dname inside it is
    always terminated with 00 (the root label). I.e. all dname are
    stored as absolute domain names.

2. Different parts of ldns:

                              - CLIENT -
                     Any program making use of ldns
            _________/\            /\                 /\
           /                       |                   \
          \/                       \/                  \/
- WIRE module -  <---->  - CENTRAL structures - <-> - RESOLVER module -
 from_wire                pkt structure              stub resolver
 to_wire                  rrlist structure           send()
 -convert from and        rrset structure            query()
  to wireformat           rr structure               bgsend()
 -all name decoding       rdf structure              axfr()
  encoding is contained   dname structure             /\ 
  in these functions          /\    /\                | 
                              /     |                 |
                        _____/      |                 |
                       /            |                 \/
- STR module -        \/            |               - NET module -
 from_str                           |                all network interfacing
 to_str                             |                code
 -convert from and to string	    |	               /\
 -dig-like output                   |                  |
 -no pretty printing                |                  \/
 -depends on some OS/libc calls     |               - OS/libc layer -
                                    |
                                    \/
                            - DNSSEC module -
                             sign()
                             verify()			 



Currently not there:
o A zone structure
o A encoder/decoder object which can be overloaded to 
  use specific functions. NSD likes to have this
o TSIG functionality
o Dynamic update function


3. CENTRAL structures

nlnetlabs.nl.   600     IN      MX      10    open.nlnetlabs.nl.
 \              \       \       \       \_                  _/
   _owner        _ttl    _klass   _type    \_  rdf[]      _/
  (rdf)     (uint16_t) (rr_class) (rr_type)
                                           10          := rdf[0]
                                    open.nlnetlabs.nl. := rdf[1]

* rdf structure:
The LHS is put in a rdf structure, which is a normal rdf but always has the
type LDNS_RDF_TYPE_DNAME.

An rdf structure has 3 members; the size, the type is carrying and a void *
pointer to the data. The data is always in uncompressed wireformat.

The RSH (rdata) is put in an array of rdf's (in this case 2).

The entire resource record is put in a RR structure, which has
the fields described above (under the RR):
  _owner	(nlnetlabs.nl.)
  _ttl		(600)
  _klass	(LDNS_RR_CLASS_IN: 'IN')
  _type         (LDNS_RR_TYPE_MX: 'MX')
  _rd_count	(2)
  _rdata_fields[rd_count]
                rdf[0]  (10)
                rdf[1]  (open.nlnetlabs.nl.)

* RR list structure:
An RR list structure is simply structure with a counter
and an array of RR structures. Different kinds of RR's can
be grouped together this way.

* RR set structure
An RR set structure is an RR list structure, but its accessor
function check if the RR's in there are: 
 - from the same type
 - have the same TTL
 - have the same ownername

This is the RFC definition of an RRset.

* pkt structure:
A pkt structure consists out of a header structure where 
packet specific flags are kept, TC, RD, IP from server which
sent the packet, etc.
Further more it is divided in 4 sections: question, authority, answer
and additional.

All four sections have the type RRlist that simply hold a list of RR's


4. WIRE module and CENTRAL structures Interface
As the WIRE module takes care of the compression/decompression
it needs a buffer which holds all the binary DNS data.
All functions will operate on such a buffer to extract specific
information which is then stored in RR structures.

5. RESOLVER module and CENTRAL structures Interface
The resolver module always returns a pkt structure. Either with
the answer or a SERVFAIL pkt.

The exact function-call parameters have not yet been 
decided on.

Also the resolver module will need to access some of the
to_wire and from_wire function to creates ldn_pkt's from
the data it receives (arrow not drawn).

6. STR module and CENTRAL structures Interface
Convert to and from strings. This module could be used
to read in a zone file (list of RRs) and convert the text strings to
the format used by ldns. Or the other way around.

7. NET Module and RESOLVER module Interface
The resolver module will get a packet and will mold it so that
it can be sent off to a nameserver. 
It might need to interface with the wire module (arrow not drawn).

8. NET Module and OS/libc Interface
OS/network calls will be used here. The Net module is the only part of 
the library where the underlying OS matters. 

9. Client program ldns Interface
Any client program will have access to
- WIRE module
- CENTRAL structure
- RESOLVER module
- STR module (arrow not drawn in the above figure)

10. DNSSEC module
The DNSSEC types are handled in the RR module, but the crypto
routines are contained in this module. This module will depend
on OpenSSL for the crypto routines. 
