dnsguide

A stub resolver is a DNS client that sends queries to a recursive DNS server. To implement one in Rust:

1. Create a DnsPacket: Initialize a new packet and set the recursion_desired flag to true in the header.
2. Add a Question: Push a DnsQuestion (containing the target domain and QueryType) into the packet's questions vector.
3. Serialize: Use packet.write(&mut buffer) to write the packet into a BytePacketBuffer.
4. Send via UDP: Use std::net::UdpSocket to send the buffer contents to the target DNS server (e.g., 8.8.8.8:53).
5. Receive Response: Use socket.recv_from to read the response into a buffer, then use DnsPacket::from_buffer to parse the received bytes back into a DnsPacket structure.

fn main() -> Result<()> {
    let qname = "google.com";
    let qtype = QueryType::A;
    let server = ("8.8.8.8", 53);

    let socket = UdpSocket::bind(("0.0.0.0", 43210))?;

    let mut packet = DnsPacket::new();
    packet.header.id = 6666;
    packet.header.questions = 1;
    packet.header.recursion_desired = true;
    packet.questions.push(DnsQuestion::new(qname.to_string(), qtype));

    let mut req_buffer = BytePacketBuffer::new();
    packet.write(&mut req_buffer)?;

    socket.send_to(&req_buffer.buf[0..req_buffer.pos], server)?;

    let mut res_buffer = BytePacketBuffer::new();
    socket.recv_from(&mut res_buffer.buf)?;

    let res_packet = DnsPacket::from_buffer(&mut res_buffer)?;
    println!("{:#?}", res_packet.header);
    // ... print questions, answers, etc.
    Ok(())
}

A DNS proxy server receives queries, forwards them to an upstream caching server (like 8.8.8.8), and returns the result to the client.

To implement this, you need to:

1. Bind a UdpSocket to a port (e.g., 2053).
2. In a loop, use socket.recv_from to capture incoming packets and the sender's address (src).
3. Parse the packet using DnsPacket::from_buffer.
4. Extract the question and use a lookup function to forward the query to an upstream server.
5. Construct a response DnsPacket with the same id, set recursion_desired and recursion_available to true, and set response to true.
6. Copy the answers, authorities, and resources from the upstream result into your response packet.
7. Handle errors by setting rescode to SERVFAIL (if lookup fails) or FORMERR (if no question is present).
8. Encode the response with packet.write and send it back to src using socket.send_to.

/// Handle a single incoming packet
fn handle_query(socket: &UdpSocket) -> Result<()> {
    let mut req_buffer = BytePacketBuffer::new();
    let (_, src) = socket.recv_from(&mut req_buffer.buf)?;
    let mut request = DnsPacket::from_buffer(&mut req_buffer)?;

    let mut packet = DnsPacket::new();
    packet.header.id = request.header.id;
    packet.header.recursion_desired = true;
    packet.header.recursion_available = true;
    packet.header.response = true;

    if let Some(question) = request.questions.pop() {
        if let Ok(result) = lookup(&question.name, question.qtype) {
            packet.questions.push(question);
            packet.header.rescode = result.header.rescode;

            for rec in result.answers { packet.answers.push(rec); }
            for rec in result.authorities { packet.authorities.push(rec); }
            for rec in result.resources { packet.resources.push(rec); }
        } else {
            packet.header.rescode = ResultCode::SERVFAIL;
        }
    } else {
        packet.header.rescode = ResultCode::FORMERR;
    }

    let mut res_buffer = BytePacketBuffer::new();
    packet.write(&mut res_buffer)?;
    let len = res_buffer.pos();
    let data = res_buffer.get_range(0, len)?;
    socket.send_to(data, src)?;

    Ok()
}

fn main() -> Result<()> {
    let socket = UdpSocket::bind(("0.0.0.0", 2053))?;
    loop {
        if let Err(e) = handle_query(&socket) {
            eprintln!("An error occurred: {}", e);
        }
    }
}

To implement writing for new record types, extend the DnsRecord::write method. For records containing variable-length label sequences (NS, CNAME, MX), use a placeholder (writing a zero size) at the start of the sequence, write the actual data, and then use BytePacketBuffer::set_u16 to go back and fill in the correct size.

impl DnsRecord {
    pub fn write(&self, buffer: &mut BytePacketBuffer) -> Result<usize> {
        let start_pos = buffer.pos();

        match *self {
            DnsRecord::A { ref domain, ref addr, ttl } => {
                buffer.write_qname(domain)?;
                buffer.write_u16(QueryType::A.to_num())?;
                buffer.write_u16(1)?;
                buffer.write_u32(ttl)?;
                buffer.write_u16(4)?;

                let octets = addr.octets();
                buffer.write_u8(octets[0])?;
                buffer.write_u8(octets[1])?;
                buffer.write_u8(octets[2])?;
                buffer.write_u8(octets[3])?;
            }
            DnsRecord::NS { ref domain, ref host, ttl } => {
                buffer.write_qname(domain)?;
                buffer.write_u16(QueryType::NS.to_num())?;
                buffer.write_u16(1)?;
                buffer.write_u32(ttl)?;

                let pos = buffer.pos();
                buffer.write_u16(0)?;

                buffer.write_qname(host)?;

                let size = buffer.pos() - (pos + 2);
                buffer.set_u16(pos, size as u16)?;
            }
            // ... other variants (CNAME, MX, AAAA, UNKNOWN)
        }

        Ok(buffer.pos() - start_pos)
    }
}

To support additional DNS record types, update the QueryType enum and implement the to_num and from_num utility functions to handle the mapping between enum variants and their numeric IDs.

Supported types in this guide:

• A (1)
• NS (2)
• CNAME (5)
• MX (15)
• AAAA (28)
• UNKNOWN(u16) (fallback)

#[derive(PartialEq, Eq, Debug, Clone, Hash, Copy)]
pub enum QueryType {
    UNKNOWN(u16),
    A,     // 1
    NS,    // 2
    CNAME, // 5
    MX,    // 15
    AAAA,  // 28,
}

impl QueryType {
    pub fn to_num(&self) -> u16 {
        match *self {
            QueryType::UNKNOWN(x) => x,
            QueryType::A => 1,
            QueryType::NS => 2,
            QueryType::CNAME => 5,
            QueryType::MX => 15,
            QueryType::AAAA => 28,
        }
    }

    pub fn from_num(num: u16) -> QueryType {
        match num {
            1 => QueryType::A,
            2 => QueryType::NS,
            5 => QueryType::CNAME,
            15 => QueryType::MX,
            28 => QueryType::AAAA,
            _ => QueryType::UNKNOWN(num),
        }
    }
}

To implement reading for new record types, update the DnsRecord enum to include the new variants and extend the DnsRecord::read method. The method should use a BytePacketBuffer to parse the preamble (domain, qtype, class, ttl, and data_len) and then match on the QueryType to parse the specific record data.

Key parsing logic for common types:

• A: Reads 4 bytes for Ipv4Addr.
• AAAA: Reads 16 bytes for Ipv6Addr.
• NS/CNAME: Reads a qname for the host.
• MX: Reads a 2-byte priority followed by a qname for the host.
• UNKNOWN: Uses buffer.step(data_len) to skip the data.

impl DnsRecord {
    pub fn read(buffer: &mut BytePacketBuffer) -> Result<DnsRecord> {
        let mut domain = String::new();
        buffer.read_qname(&mut domain)?;

        let qtype_num = buffer.read_u16()?;
        let qtype = QueryType::from_num(qtype_num);
        let _ = buffer.read_u16()?;
        let ttl = buffer.read_u32()?;
        let data_len = buffer.read_u16()?;

        match qtype {
            QueryType::A => {
                let raw_addr = buffer.read_u32()?;
                let addr = Ipv4Addr::new(
                    ((raw_addr >> 24) & 0xFF) as u8,
                    ((raw_addr >> 16) & 0xFF) as u8,
                    ((raw_addr >> 8) & 0xFF) as u8,
                    ((raw_addr >> 0) & 0xFF) as u8,
                );

                Ok(DnsRecord::A {
                    domain: domain,
                    addr: addr,
                    ttl: ttl,
                })
            }
            // ... other variants (AAAA, NS, CNAME, MX, UNKNOWN) 
        }
    }
}