ANDNS PROTOCOL

0. - INTRODUCTION -

   This document describes the protocol used to communicate with ANDNA.
   This protocol is used also to make query in internet realm.
   So, we can query for `google.it` in internet, or for `depausceve`
   in the netsukuku net.

   In the case of internet queries, the dns_wrapper will contact the
   dns-servers specified in /etc/resolv.conf when ntkd is loaded.

1. - NOTATIONS -

   In the next section, we represent a byte with this graphic:

         1  2  3  4  5  6  7  8
        +--+--+--+--+--+--+--+--+
        |                       |
        +--+--+--+--+--+--+--+--+

   The numbers represent the bits
   Let's show two bytes:

         1  2  3  4  5  6  7  8  1  2  3  4  5  6  7  8
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                       |                       |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

2. - HEADERS -

  Headers are 4-byte long, and the format is:

        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                      ID                       |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |QR| P|  QTYPE |  ANCOUNT  |I |   NK|   RCODE   |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

  where:

        ID      =  It's a 2-byte value which identifies the query.
                   ID is choosed in a random way and the future
                   answers must have the same ID.

        QR      =  0 implies that this packet contains a question
                   1 if the packets contains answers

        P       =  If the query is h2ip and ntk-related, P specifies
                   the protocol service:
                   0 for TCP
                   1 for UDP
                   P has to be zero otherwise.

        QTYPE   = Query Type. See below.
                  Note: answers must leave this field unchanged.

        ANCOUNT = Answer Count. This field is set only if QR=1,
                  ie if this packet contains answers.
                  ANCOUNT is the number of answers which belongs
                  to this packet.

        I       = Ip-version bit. Specifies the ip version for the
                  packet contents. All addresses contained in the 
                  packet are:
                  if I==0    IPv4 addresses (4-bytes)
                  if I==1    Ipv6 addresses (16-bytes)
                  This bit is useful only for questions. The server 
                  will reply "NO SUCH DOMAIN" if his node is running
                  with a different ip-version.
                  Otherwise, only IPs of the same family will be 
                  returned.
                  
        NK      = Netsukuku bit. With this field, you can specify
                  the query realm.
                  If NK=1, the realm is netsukuku.
                  If NK=2, the realm is internet.
                  If NK=0, the packet is not encoded with this
                  protocol, but with standard DNS protocol.
                  To specify realms with DNS protocol, see below.
                  Note: answers must leave this field unchanged.

        RCODE   = This is the result of a query.
                  RCODE has to be 0 if this packet contains a
                  question.
                  In the case of errors, ANCOUNT has to be 0.

3. - QUERY TYPE -

  There are different kind of questions:

  QTYPE = 0
        This is the classic resolution `hostname -> ip`.
        A gethostbyname.
        Note: this type of query is used also for SNSD
        resolution (see `NTK_RFC 0009`).
        You can specify a service.
        So, the general way to represent this query is:

                hostname:service -> ip

        If you don't specify a service, the 0-service
        will be used.

        Example: if you want to discover which address is
        hosting the http service of hostname `depausceve`,
        you have to formule this query:

                depausceve:80

        See below how to formule queries.

  QTYPE = 1
        This is a reverse resolution: `ip -> host`.

4. - QUERY REALMS -

  A query can be formulated to find some object in the
  netsukuku net or in internet.
  Maybe you want to know the ip of `google.it`, but you
  have to specify where: internet or netsukuku?

  If you use ANDNS protocol, you specify this with NK
  bit (See the HEADERS SECTION).

  If you use DNS protocol, you have to formule the query
  with some suffix: if you ask for `google.it.int` (or
  google.it.INT), the question is made in internet.
  If you ask for `google.it.ntk` (or `google.it.NTK)
  the question is made in netsukuku.
  If you don't specify any suffix, the default realm
  is ****************************

  The dns_wrapper first search for a suffix, understanding
  the correct realm.
  If the question does not have any suffix, the query
  will be made in the default realm.
  Otherwise, dns_wrapper removes this suffix and
  resolves the query without it.

5. - RCODE -

  This is the answer report.
  It's always 0 if the packet carries a question.
  Possible values, in the case of an answer, are:

   RCODE = 0 No Error.
        This answer contains answers.
        The number of ANSWERS is ANCOUNT (see
        HEADERS SECTION).

   RCODE = 1 Interpretation Error.
        The server did not understand your query.
        In other words, your question is malformed.

   RCODE = 2 Server Fail.
        The server did encounter some error processing
        your question. Your question is good.

   RCODE = 3 No Such Domain
        The object of your question does not exist.

   RCODE = 4 Not Implemented
        This type of query is not implemented yet
        in this server.

   RCODE = 5 Refused
        The server refuse to talk with you.

  Note: this expression is always true:

                (RCODE XOR ANCOUNT)

  ie, if RCODE contains some error (RCODE!=0), there is
  not answer in this packet. If RCODE is 0 (no error),
  the packet contains some answer.

6. - QUESTIONS -

  There are three types of questions.
  We have to switch the value QTYPE against realm.

  - Case QTYPE = 0 (h2ip) AND Realm=NTK
    The format of the question is:

        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                    SERVICE                    |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                                               |       
        |                                               |       
        |                                               |
        |                   HOSTNAME                    |
        |                     HASH                      |
        |                     (HH)                      |
        |                                               |
        |                                               |
        |                                               |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

    where:

     SERVICE is a 2-byte field and represents the SNSD service
     value (see `NTK_RFC 0009`).

     HH is the 16-bytes hostname hash.

  - Case QTYPE = 0 (h2ip) AND Realm=INET
    The format of the question is:

        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                   SERVICE                     |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                   RDLENGTH                    |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                                               |
        \                                               \
        \                    RDATA                      \
        |                                               |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

    where:

     SERVICE is a 2-byte field and represents the SNSD service
     value (see `NTK_RFC 0009`). At this moment, for INET 
     resolutions, the service is limited to value 25 
     - TCP is assumed - or 0.

     RDLENGTH is the RDATA len

     RDATA is a hostname string, such that:
                 strlen(RDATA)=RDLENGTH

  - Case QTYPE = 1 (ip2h).
    The format of the question is:

        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                                               |
        /                     RDATA                     /
        /                                               /
        |                                               |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

    where:

     RDATA is an IP in the binary format.
     The length of the field - ie the family address (4 or 6) -
     depends on the bit `I' in the headers section. 
   

7. - ANSWERS -

  The format of answers is always of the type:

        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        | R|        WG          |       PRIO            |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                    RDLENGTH                   |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |                                               |
        /                     RDATA                     /
        /                                               /
        |                                               |
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

  Let's switch QTYPE to explain the contents of answers.

  CASE QTYPE=0   (h2ip)

   We are searching for ip. SNSD introduces the possibility that
   an answer for the question `depausceve:80` could be `frenzu:0`
   or an IP. We have to know which is the case.
   We use the R-bit for that.
   It is the Recursion bit. If it's set, we have a hostname as
   answer (for example `frenzu:0`).
   If the R-bit is set on headers, dns_wrapper will resolve
   automatically this answer and will send to the client the
   IP resolution.
   If the R-bit is not set on headers, this answer will be
   sent to the client. It will be the client, eventually, to
   resolve it.

   Otherwise, if RDATA carries an IP, R is set to 0.
   In this case, the answer is completed yet.

   WG is the weigth of an answer (see `NTK_RFC 0009`)
   PRIO the priority (see `NTK_RFC 0009`)

   RDLENGTH is the RDATA-len, and it's such that:

   -   If R=0, RDATA is an IP. So, RDLENGTH is 4 or 16 (IPv4 or IPv6).
   -   If R!+0, RDATA is a string and RDLENGTH his strlen.

  CASE QTYPE=1   (ip2h)

   In this case, answers need to carry hostnames.
   RDATA is the hostname string, and RDLENGTH his strlen.
   R is always 0.

   WG is the weigth of an answer (see `NTK_RFC 0009`)
   PRIO the priority (see `NTK_RFC 0009`)