A Really Stupid DNS Server

Keenan Gugeler — Tue, 03 Jun 2025 00:00:00 +0000
I manage my certificates with Let's Encrypt, and for a while now I've been using the DNS challenge for its ability to get wildcard certificates. This makes it easy for me to set up a new subdomain, without having to reconfigure my certificate.</p>
I used to use Cloudflare's API to manage the TXT records, but I swapped some time ago to having a NS record for _acme-challenge.kgugeler.ca</code> point to my VPS, and when I want to renew my certificate, I spawn a public BIND instance. This method is mentioned by Let's Encrypt</a>.</p>
Recently I had a bad idea. BIND is a complex DNS server, right? What if I could replace it with a small server. After all, it's not doing much. What could go wrong?</p>
DNS</a></h1>
Ok, so I know that DNS uses UDP over port 53, and I know it has a recursive
structure, and I know about the different record types but... how do I make a
DNS query? What does it look like on the wire?</p>
Thankfully
Wikipedia</a>
has me covered. We've got a short header, and then a list of questions,
answers, authority records, and additional records. The questions are sent in
queries and repeated in responses. The answers are records that are answers to
the questions. Authority records are what we get when the server redirects us
to other name servers, and Additional records "relate to the query but are not
strictly answers for the question". Let's look at a simple DNS query to the
root name servers:</p>
> dig @a.root-servers.net kgugeler.ca</span></span>
</span>
; <<>> DiG 9.20.9 <<>> @a.root-servers.net kgugeler.ca</span></span>
; (2 servers found)</span></span>
;; global options: +cmd</span></span>
;; Got answer:</span></span>
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 65458</span></span>
;; flags: qr rd; QUERY: 1, ANSWER: 0, AUTHORITY: 4, ADDITIONAL: 9</span></span>
;; WARNING: recursion requested but not available</span></span>
</span>
;; OPT PSEUDOSECTION:</span></span>
; EDNS: version: 0, flags:; udp: 4096</span></span>
;; QUESTION SECTION:</span></span>
;kgugeler.ca.			IN	A</span></span>
</span>
;; AUTHORITY SECTION:</span></span>
ca.			172800	IN	NS	d.ca-servers.ca.</span></span>
ca.			172800	IN	NS	any.ca-servers.ca.</span></span>
ca.			172800	IN	NS	c.ca-servers.ca.</span></span>
ca.			172800	IN	NS	j.ca-servers.ca.</span></span>
</span>
;; ADDITIONAL SECTION:</span></span>
d.ca-servers.ca.	172800	IN	A	45.142.220.101</span></span>
d.ca-servers.ca.	172800	IN	AAAA	2a0e:dbc0::101</span></span>
any.ca-servers.ca.	172800	IN	A	199.4.144.2</span></span>
any.ca-servers.ca.	172800	IN	AAAA	2001:500:a7::2</span></span>
c.ca-servers.ca.	172800	IN	A	185.159.196.2</span></span>
c.ca-servers.ca.	172800	IN	AAAA	2620:10a:8053::2</span></span>
j.ca-servers.ca.	172800	IN	A	198.182.167.1</span></span>
j.ca-servers.ca.	172800	IN	AAAA	2001:500:83::1</span></span></code></pre>
We see that there are 4 authority records to point us to the nameservers for
the CA TLD - any of the four records will do. We don't have any way of knowing
their IPs, which is why those IPs appear in the additional section1</a></sup>.</p>
It's also worth noting that dig</code> requested recursion, meaning it requested
the root nameserver to walk the DNS hierarchy for it, and the root nameserver
(naturally) declined - doing recursive DNS processing safely is hard.</p>
Question</a></h2>
A question in the question section is simple enough: we need a name, a type of
record, and a class. For our purposes the class will always be IN, the internet
class.</p>
Err, hold on, how is that name encoded?</p>

The domain name is broken into discrete labels which are concatenated; each
label is prefixed by the length of that label.</p>
</blockquote>
That's not very specific... thankfully the
RFC</a> has me covered. Each component of
the domain is encoded by adding a single byte for the length, and then the
content. Don't forget about root domain .</code>! So kgugeler.ca</code> becomes 08 6b 67 75 67 65 6c 65 72 02 63 61 00</code>, where the last zero byte indicates a component
of length zero, the root2</a></sup>.</p>
Resource Records</a></h2>
These are pretty similar - we need a name, type, and class, just like
questions. Then, we need a TTL and the actual data: which is also encoded with
length + value. The actual value format is type-specific.</p>
For the purposes of this post, only TXT records matter, and they are encoded as
length + value. This means that a TXT record for kgugeler.ca looks like the
following:</p>
// kgugeler.ca.</span></span>
08 6b 67 75 67 65 6c 65 72 02 63 61 00</span></span>
// TXT is type 16</span></span>
00 10</span></span>
// IN is class 1</span></span>
00 01</span></span>
// TTL of one minute = 60 seconds</span></span>
00 00 00 3c</span></span>
// Our data has length 4</span></span>
00 04</span></span>
// Our data is encoded as one length byte + value</span></span>
// This says "DNS"</span></span>
03 44 4e 53</span></span></code></pre>
Note that the TXT records ends up having two length fields, one outer, one inner.</p>
Name Compression</a></h2>
So far, the protocol seems simple to parse and generate, right? Sure, there are
a lot of resource record types, but other than that, super easy!</p>

In order to reduce the size of messages, the domain system utilizes a
compression scheme which eliminates the repetition of domain names in a
message. In this scheme, an entire domain name or a list of labels at the end
of a domain name is replaced with a pointer to a prior occurance of the same
name.</p>
</blockquote>
Uh, what?</p>
So it turns out that by enforcing that the lengths of domain name components
are at most 63 bytes, we can use the upper two bits to signal some other thing.
In this case, if the upper two bits are both one, then the next 14 bits (two
bytes total) are used as a "pointer" into the message. Any other upper bit
pattern is reserved.</p>
The pointer is just an offset from message start. The idea is that if we have a
question kgugeler.ca IN TXT</code>, we have to spell out kgugeler.ca</code>. But in the
answer, when we need to put the name down again, we can use a pointer:</p>
// Question</span></span>
// kgugeler.ca.</span></span>
08 6b 67 75 67 65 6c 65 72 02 63 61 00</span></span>
// ...</span></span>
// Answer: this is a pointer to offset 16 from message start</span></span>
c0 10</span></span></code></pre>
We can also have only some suffix be a pointer:</p>
// hi + pointer to offset 16</span></span>
02 68 69 c0 10</span></span></code></pre>
This is a useful feature! Unfortunately, the RFC does not make any suggestions
on how to restrict this to ease processing. For instance, if pointers always
had to point to smaller offsets, then termination is guaranteed. Or if pointers
couldn't point at other pointers, then termination is guaranteed since each
pointer will always point to something that increases the length of the domain
name, and the domain name has a limit of 255.</p>
I decided to assume that pointers won't point at other pointers, which seems
reasonable.</p>
Parsing</a></h1>
Okay, now we can finally parse messages! Here's the segment of the parsing code
that actually handles names. The rest is pretty boring, but you can see it
here</a>.</p>
class</span> Consumer</span>:</span></span>
    def</span> __init__</span>(</span>self</span>,</span> packet</span>:</span> bytes</span>):</span></span>
        self</span>.</span>packet</span> =</span> packet</span></span>
        self</span>.</span>offset</span> =</span> 0</span></span>
</span>
    def</span> consume_bytes</span>(</span>self</span>,</span> size</span>:</span> int</span>) -></span> bytes</span>:</span></span>
        assert</span> self</span>.</span>offset</span> +</span> size</span> <=</span> len</span>(</span>self</span>.</span>packet</span>)</span></span>
        data</span> =</span> self</span>.</span>packet</span>[</span>self</span>.</span>offset</span> :</span> self</span>.</span>offset</span> +</span> size</span>]</span></span>
        self</span>.</span>offset</span> +=</span> size</span></span>
        return</span> data</span></span>
</span>
    def</span> consume_ubyte</span>(</span>self</span>) -></span> int</span>:</span></span>
        return</span> struct</span>.</span>unpack</span>(</span>">B"</span>,</span> self</span>.</span>consume_bytes</span>(</span>1</span>))[</span>0</span>]</span></span>
</span>
    def</span> consume_name</span>(</span>self</span>) -></span> Name</span>:</span></span>
        components</span> =</span> []</span></span>
        total_length</span> =</span> 0</span></span>
</span>
        label_length</span> =</span> self</span>.</span>consume_ubyte</span>()</span></span>
        while</span> 0</span> <</span> label_length</span> <=</span> 0x</span>3F</span>:</span></span>
            total_length</span> +=</span> label_length</span></span>
            assert</span> total_length</span> <=</span> 255</span></span>
            components</span>.</span>append</span>(</span>self</span>.</span>consume_bytes</span>(</span>label_length</span>))</span></span>
            label_length</span> =</span> self</span>.</span>consume_ubyte</span>()</span></span>
</span>
        if</span> label_length</span> !=</span> 0</span>:</span></span>
            assert</span> label_length</span> &</span> 0x</span>C0</span> ==</span> 0x</span>C0</span></span>
            offset</span> =</span> (</span>label_length</span> &</span> 0x</span>3F</span>)</span> <<</span> 8</span> |</span> self</span>.</span>consume_ubyte</span>()</span></span>
            components</span>.</span>extend</span>(</span>self</span>.</span>resolve_label_pointer</span>(</span>offset</span>,</span> total_length</span>))</span></span>
</span>
        return</span> Name</span>(</span>components</span>=</span>components</span>)</span></span>
</span>
    def</span> resolve_label_pointer</span>(</span>self</span>,</span> offset</span>,</span> total_length</span>) -></span> list</span>[</span>bytes</span>]:</span></span>
        # Store global offset for restoring later</span></span>
        self</span>.</span>offset</span>,</span> offset</span> =</span> offset</span>,</span> self</span>.</span>offset</span></span>
</span>
        components</span> =</span> []</span></span>
</span>
        # Disallow double pointer to avoid DoS</span></span>
        allow_pointer</span> =</span> False</span></span>
</span>
        while</span> True</span>:</span></span>
            first_byte</span> =</span> self</span>.</span>consume_ubyte</span>()</span></span>
            if</span> first_byte</span> ==</span> 0</span>:</span></span>
                break</span></span>
            elif</span> first_byte</span> <=</span> 0x</span>3F</span>:</span></span>
                total_length</span> +=</span> first_byte</span></span>
                assert</span> total_length</span> <=</span> 255</span></span>
                components</span>.</span>append</span>(</span>self</span>.</span>consume_bytes</span>(</span>first_byte</span>))</span></span>
                allow_pointer</span> =</span> True</span></span>
            else</span>:</span></span>
                assert</span> allow_pointer</span>,</span> "Pointer to pointer in message"</span></span>
                assert</span> first_byte</span> &</span> 0x</span>C0</span> ==</span> 0x</span>C0</span></span>
                # Set the global offset and continue</span></span>
                self</span>.</span>offset</span> =</span> (</span>first_byte</span> &</span> 0x</span>3F</span>)</span> <<</span> 8</span> |</span> self</span>.</span>consume_ubyte</span>()</span></span>
</span>
        # Restore global offset</span></span>
        self</span>.</span>offset</span>,</span> offset</span> =</span> offset</span>,</span> self</span>.</span>offset</span></span>
</span>
        return</span> components</span></span></code></pre>
Debugging this code wasn't too bad, since we can send a request to the server
with dig</code> and look through it with either python or Wireshark.</p>
Serialization is even easier, since we aren't obligated to output pointers.</p>
Flags</a></h2>
One thing I neglected to mention earlier are the message flags. This is a
16-bit field that contains several flags, including whether the message is a
query or reply, the OPCODE, whether recursion is desired by the client, whether
recursion is available on the server, and the response code. This isn't too
important for parsing, but we need to know this format for generating our
responses. I didn't bother to check the flags sent much.</p>
Rewriting it in Rust</a></h1>
For some insane reason, I thought that it would be easier to write this parser
in Rust3</a></sup>, since Rust has helpers for dealing with conversions to/from binary
data. It was about the same. I don't know what I expected... but I did make a
fun realization while writing it in Rust.</p>
Throwing the Parser out the Window</a></h1>
Wait, why are we writing a DNS server again?</p>
ACME</a></h2>
The Automated Certificate Management
Environment</a>
protocol is used to request a certificate. Let's Encrypt then issues a
challenge, in our case, a DNS challenge: we have to prove that we control the
domain by placing a TXT record in the domain DNS records.</p>
Who needs a Parser</a></h2>
Hold on, if all we need to do is serve a record from a single domain name, why
do we need a parser? We can just ignore what clients ask entirely!</p>
Well, okay, not entirely. The first two bytes of the query are a transaction
ID, and if that's different in our reply, DNS clients won't recognize our
response4</a></sup>.</p>
What happens if a client asks a different question?</p>
> dig @127.0.0.1 sourcehut.org</span></span>
;; ;; Question section mismatch: got kgugeler.ca/TXT/IN</span></span></code></pre>
Dig is not happy5</a></sup>.</p>
Does it work?</a></h1>
Yes, it works! I can actually get a certificate provisioned this way. It's not
pretty, since there's no easy way to dynamically add a new record yet, but it
works!</p>
One interesting thing I found out while doing this is that Let's Encrypt
queries the DNS server from multiple locations, in order to prevent BGP
hijacking</a>.</p>
Automating it</a></h1>
Naturally, my first thought here is to use Certbot hooks to spawn the server. There are two main issues here:</p>

I need to spawn the server in the background and wait for the cleanup hook
to stop it. A natural choice is to use OpenRC since I'm on Alpine, but then
the service needs to know the challenge token to serve.</li>
I want a certificate for kgugeler.ca</code> and *.kgugeler.ca</code>... but that means
I need to put two records on _acme-challenge.kgugeler.ca</code>, so I need to
support that.</li>
</ol>
Rewriting it in Go??</a></h2>
I was briefly tempted to write the server in Go and integrate with
lego</a>, since it has a Go Library. I eventually
decided not to, since then I'd have to remember to rebuild everytime lego
updates, and I'm lazy.</p>
Control Socket</a></h2>
An easier solution is to simply spawn the server without any TXT records
configured. Then, use a control socket to add challenges to the domain.</p>
I was initially going to use a TCP socket with a simple length + value
encoding, but it's even easier to just use a UDP socket and have the whole
packet be the record to add. Dead simple.</p>
Now the flow goes like this:</p>

Certbot hook runs, the server is started if it hasn't been already. A record gets added.</li>
The hook is run again, adding another record via the control socket.</li>
Let's Encrypt verifies the record.</li>
The cleanup hook stops the server.</li>
</ol>
This is much nicer to package and script!</p>
But... why?</a></h1>
One reason Let's Encrypt gives for having a separate nameserver for the
_acme-challenge</code> subdomain is security: no need to have a DNS API credential
on your VPS. And indeed, this is a benefit. The primary reason I swapped to
BIND in the first place though was speed: it's instantaneous to verify records,
since I can simply set a TTL of 1 second, and they deploy immediately.</p>
But why write this server? It's way simpler than BIND - the entire server is 86
lines of python code. It doesn't do any parsing or validation or anything on
untrusted input: it reads two bytes and dumps a pregenerated response.</p>
Limitations</a></h1>
Uh... basically every limitation you can think of?</p>
There's no way this server is close to standards compliant, it can't handle
multiple domains at once, it's not supported by any existing tools...</p>
This kind of idea isn't new though - Joohoi's
ACME-DNS</a> is a simple DNS server for
handling ACME DNS-01 challenges, and is supported by Lego. I haven't looked at
the code much, but it's probably what I'd recommend to people looking for a
similar setup... there's no way this hack is something I can recommend.</p>
It's very amusing to me that this project works at all, and it's cool how
simple the code ends up being. Of course all the ACME work is being done
elsewhere, but the fact that we can solve a DNS challenge in such a stupid
fashion is both hilarious and satisfying.</p>




If you're paying really close attention, you'll see that we got 9
additional records. The last one is for DNS extensions, which I didn't have
to look into, so I can't explain it to you. ↩</a></p>
</li>

All domain names technically end with a
dot</a>, that is almost always
omitted. ↩</a></p>
</li>

If you're curious</a> ↩</a></p>
</li>

Dig gives ;; Warning: ID mismatch: expected ID 54268, got 26729</code>. ↩</a></p>
</li>

"Hello please give me the IP of sourcehut.org" "HELLO HAVE A
TXT RECORD FOR AN UNRELATED DOMAIN" "what" ↩</a></p>
</li>
</ol>
</section>
- Keenan's Blog

A Really Stupid DNS Server
