Writing your own DNS Query Client
===

## Table of Contents

[TOC]

Over the summer, I had the opportunity to intern at Carbonteq. The assignment was to understand the DNS protocol and the implementation of its client side. I didn't know anything at first, but with research and guidance, I began to understand the logic and operation of the DNS client. Along with this, I began learning about various techniques, principles, and practices that assisted us in writing code that was easier to read, test, debug, and extend. The experience was enjoyable because I learned a lot. You may be wondering what a DNS client is, I got you covered.

## What is a DNS Query Client

When a browser/machine/actor needs to resolve a host name into its IP address, it sends a request packet to the DNS server, which returns the IP address of the remote host as a response packet.


## DNS Packet Structure

DNS is quite convenient in the sense that requests and responses use almost the same format. Each message consists of a header section and four other sections: question, answer, authority, and an additional section.

| Section | Size |
|:---------- | -------- |
| Header | 12 Bytes |
| Question | Variable |
| Answer | Variable |
| Authority | Variable |
| Additional | Variable |

### DNS Header
---

**ID** : A 16 bit identifier that generates randomly. ID remains the same when the response packet arrives.
**QR** : A 1 bit flag i.e. 0 for queries, 1 for responses.
**OPCODE** : A 1 bit flag that is typically set to 0 for which represents a *standard query*.
**AA** : A 1 bit flag only meaningful in responses, and specifies whether the responding name server owns the queried domain or not.
**TC** : A 1 bit flag specifying if the message has been truncated. Our message was short i.e. limited to 512 bytes , and won’t need to be truncated, so we can set this to 0.
**RD** : A 1 bit flag specifying if recursion is desired. If the DNS server doesn’t know the answer to our query, it can recursively ask other DNS servers. In our project we set the recursion to 1.Recursive query support is optional.
**RA** : A 1 bit flag specifying whether the recursive query support is available in the [Name Server](https://en.wikipedia.org/wiki/Name_server) or not. 1 for available 0 for not available.
**Z** : A 3 bit flag reserved for the later use.
**RCODE** : A 4 bit flag is set as part of responses.The values and there interpretation is given below.
| Value | Interpretation |
| ----- | ------------------ |
| 0 | No error condition |
| 1 | Format error |
| 2 | Server failure |
| 3 | Name Error |
| 4 | Not Implemented |
| 5 | Refused |

**QDCOUNT** : A 16 bit integer simply specifying the number of entries in the question section.
**ANCOUNT** : A 16 bit integer specifying the number of answers in the answer section. Initially this field is set to 0 in the request packet. In the response packet this may change depending upon the number of responses.
**NSCOUNT** : A 16 bit integer specifying the number of entries in the Authority Section
**ARCOUNT** : 16 bit integer specifying the number of entries in the Additional Section

### DNS Questions
---

**QNAME** : This contains the hostname who’s IP address we wish to find. It is encoded as a series of ‘labels’ i.e. a Label Sequence terminated by a null byte. Each label corresponds to a section of the hostname preceded by it's length as 1-byte integer.E.g "www.google.com" contains 3 sections.The first one will be www => ==03 77 77 77== , with the first byte 03 specifying the length of this section, an the rest being the encoded ascii representation of each character in www. Similarly, google would be encoded as ==06 67 6f 6f 67 6c 65== and com as ==03 63 6f 6d==. The whole encoded hostname would therefore be ==03 77 77 77 06 67 6f 6f 67 6c 65 03 63 6f 6d 00==. The last byte here is the null byte representing the end of this Label Sequence.

**QTYPE** : A 2 byte code which specifies the type of the query.
**QCLASS** : A 2 byte code that specifies the class of the query. For example, the QCLASS field is almost always set to 1 i.e. IN for the Internet.

### DNS Answers
---

**NAME** : The domain name that was queried.
**TYPE** : A 2 byte field containing one of the Query Type codes.
**CLASS** : A 2 byte field which specifies the class of the data in the RDATA field.
**TTL** : A 4 byte filed that represent the number of seconds the results can be cached.
**RDLENGTH** :A 2 byte field representing the length of the record type specific data.

**RDATA** : The data of the response. The format is dependent on the TYPE field: if the TYPE is for A records, then this is the IP address (4 bytes).

## Implementation
After plenty of research and understanding we finally dove right into the implementation.The primary task was to pack and parse the DNS packets.
### Goals

The primary goal of the implementation was to pack DNS query packet in a proper manner as investigated in the DNS protocol.Send it over to the socket. And finally parse the response after receiving it from the socket.

Create proper abstractions in order to make the code simple and easy to understand.

We may not use any external library.

In order to achieve the above goals we created a package. It enables us to construct the DNS packet using a single call (==DNSQuery.ipv4('google.com')==) and then parse the response packet using multiple calls one for each section i.e. header, question and answer. You may iterate over the question and answer call depending upon the number of questions and the number of answers.

The modules we used were [Node:Buffer](https://nodejs.org/api/buffer.html) for packing and parsing, and [Node:Dgram](https://nodejs.org/api/dgram.html) for creating socket.

### DNS Parsing and Packing
---
#### Creating a Buffer

We created our own wrapper class around the Node:Buffer which provides us with some extra functionality required for our project along with adding another level of abstraction.

~~~typescript
import { Buffer } from 'node:buffer';

export class DNSBuffer {
private _offset: number;
private _data: Buffer;

constructor(capacity = 512) {
this._offset = 0;
this._data = Buffer.alloc(capacity);
}
~~~

#### Parsing a DNS Query:
Since the response from the socket is also a DNSBuffer which also contains bytes data so we now have to convert it back into desired data type.
~~~typescript
readByte(): number {
const val = this._data.readUint8(this._offset);
this._offset++;
return val;
}

readShort(): number {
const val = this._data.readUint16BE(this._offset);
this._offset += 2;
return val;
}

readInt4(): number {
const val = this._data.readUint32BE(this._offset);
this._offset += 4;
return val;
}

readString(string_length: number): string {
const str = this._data
.subarray(this.offset, this.offset + string_length)
.toString();
this._offset += string_length;

return str;
}

~~~
#### Packing a DNS Query:
We packed the data into the DNSBuffer which was then sent over to the DNS server through a socket.

##### Writing to a Buffer
~~~typescript
writeStr(str: string) {
this._data.write(str, this._offset);
this._offset += str.length;
}

writeByte(val: number) {
// todo: check if val is byte
this._data.writeUInt8(val, this._offset);
this._offset++;
}

writeShort(val: number) {
//write
this._data.writeUInt16BE(val, this._offset);
this._offset += 2;
}

writeInt4(val: number) {
//write
this._data.writeUint32BE(val);
this._offset += 4;
}

~~~

## Scope
Our Client works for A type and CNAME type queries.

## Our Learning Outcomes
### Technical:
1. Understanding of the DNS protocol.
2. What actually is a DNS client and what does it do.
3. The detailed working of a DNS client.
4. The structure of the requests and responses.
5. Types of requests i.e. A,AAAA,CNAME etc.
6. Bit Masking.
7. The packing of the requests and the parsing of their responses which we did using node "Buffer". One important thing to keep in consideration here is that the packing and parsing must be done in "network byte order" i.e. Network Endian because the TCP/IP Internet protocol also uses big endian/network endian regardless of the hardware at either end.
8. Debugging and running unit tests.
9. Best Practices and principles which make your code simple, readable and easier to understand, test, debug and extend.
10. Version control using git.

### Non-Technical:
1. Team work
2. Work ethics
3. Meeting deadlines
4. Doing efficient research
5. Resource utilization

# Conclusion
It was quiet a wonderful experience. Working through the DNS client and getting to know how it works was very interesting. Without a doubt implementing it was even more interesting. Assuredly we can say that our days were productive.

You can find our project at GitHub. https://github.com/usman7384/typescript-dns-client