nish/net/dns-message

A DNS query for one A or AAAA question written into the caller's buffer, and the reply to it read back into addresses.

import {
  DNS_ADDRESS_BYTES,
  DNS_CLASS_IN,
  DNS_ERR_COUNT,
  DNS_ERR_EMPTY_LABEL,
  DNS_ERR_HEADER,
  DNS_ERR_HOPS,
  DNS_ERR_ID,
  DNS_ERR_LABEL_LONG,
  DNS_ERR_LABEL_TYPE,
  DNS_ERR_NAME_BYTE,
  DNS_ERR_NAME_LONG,
  DNS_ERR_NOT_REPLY,
  DNS_ERR_OPCODE,
  DNS_ERR_POINTER,
  DNS_ERR_QTYPE,
  DNS_ERR_QUESTION,
  DNS_ERR_RCODE,
  DNS_ERR_RDATA,
  DNS_ERR_RDLENGTH,
  DNS_ERR_SHORT,
  DNS_ERR_SPACE,
  DNS_MAX_ANSWERS,
  DNS_MAX_LABEL_BYTES,
  DNS_MAX_NAME_BYTES,
  DNS_MAX_POINTER_HOPS,
  DNS_NOERROR,
  DNS_NXDOMAIN,
  DNS_QUERY_MAX_BYTES,
  DNS_REFUSED,
  DNS_SERVFAIL,
  DNS_TYPE_A,
  DNS_TYPE_AAAA,
  DNS_TYPE_CNAME,
  DnsReply,
  dnsBuildQuery,
  dnsParseReply,
} from "nish/net/dns-message";
import {
  DnsReply, DNS_ADDRESS_BYTES, DNS_NOERROR, DNS_QUERY_MAX_BYTES, DNS_TYPE_A,
  dnsBuildQuery, dnsParseReply,
} from "nish/net/dns-message"

const query: u8[] = new Array<u8>(DNS_QUERY_MAX_BYTES)
// A sketch: `id` is a fresh random 16-bit number for each query, and
// `msg` a u8[] the program reads `mlen` bytes of reply into.
const qlen: i32 = dnsBuildQuery(query, id, "example.com", DNS_TYPE_A)   // < 0: a DNS_ERR_* code
// ... send query[0, qlen), read the datagram into msg[0, mlen) ...
const reply: DnsReply = new DnsReply()
const status: i32 = dnsParseReply(msg, mlen, query, qlen, 443, reply)
if (status === DNS_NOERROR && !reply.truncated) {
  // reply.addresses[i * DNS_ADDRESS_BYTES, +18) for i < reply.count, each with reply.ttls[i]
} // DNS_NXDOMAIN, DNS_SERVFAIL, DNS_REFUSED: the server's answer; < 0: a DNS_ERR_* code

A stub resolver sends one question over UDP and reads whatever datagram comes back to its port, so every byte of a reply is the peer's: a name compressed into a loop, a count of 65,535 answers in a 40-byte message, an A record five bytes long. This module reads a reply against the query it answers and refuses each of those with its own code:

Nothing is allocated per message

The query is written into the caller's array and the reply read into a DnsReply the caller made once and passes again; dnsParseReply resets it first. A window outside its array is a bug in the caller and panics; nothing a peer sends does, and the work is linear in the reply's length.

A reply must answer the query

Its ID, its QR bit, opcode 0, exactly one question, and that question's name (compared without case, as RFC 4343 asks), type and class must all be the query's, or the reply is refused before any record is read: it is not an answer to this question.

Names are bounded

A compression pointer must point before the start of the run of labels that holds it, so every hop moves backwards and a loop is impossible; at most DNS_MAX_POINTER_HOPS (16) hops are followed, a name is at most 255 bytes in wire form, and the label types RFC 6891 retired (0x40, 0x80) are refused.

Only the question's name is answered

Records are read in message order, and the chain starts at the question's name: a CNAME whose owner is the chain's end moves the end to its target, and an A or AAAA record of the asked type whose owner is the chain's end is kept. Every other record is read past, so an answer for a name nobody asked about never becomes an address. The first DNS_MAX_ANSWERS (8) addresses are kept and the rest counted in dropped.

Addresses are the 18-byte form

Addresses are the 18-byte form of docs/LANGUAGE.md: sixteen bytes of IPv6, an IPv4 address as ::ffff:a.b.c.d, then the caller's port big-endian, so one can be handed to a connect as it stands.

The record of what this module refuses and why is docs/security/dns.md.

Functions

dnsBuildQuery

Writes the query for name and qtype into out from offset 0: the ID, RD set, one question of class IN, and no EDNS record. Answers the query's length, or a DNS_ERR_* code with out partly written.

name is ASCII, its labels split on ., and one trailing . is read as the root it names. id is the caller's: a resolver draws it at random, so that a spoofed reply must guess it, and passes the same query to dnsParseReply. Nothing is allocated, and nothing is written past out.length.

const dnsBuildQuery: (
  out: u8[],
  id: i32,
  name: string,
  qtype: i32,
) => i32
outu8[]required

Where the query goes, from offset 0; DNS_QUERY_MAX_BYTES (271) bytes always have room for any name that is one.

idi32required

The query ID, 0 to 0xFFFF; any other value panics.

namestringrequired

The name to ask, such as "example.com" or "example.com.": bytes 33 to 126 (printable ASCII without the space), labels of 1 to 63 bytes, at most 253 bytes without the trailing dot.

qtypei32required

DNS_TYPE_A or DNS_TYPE_AAAA; any other is DNS_ERR_QTYPE.

returnsi32

The query's length in bytes, written to out[0, length), or a negative DNS_ERR_* code: DNS_ERR_QTYPE, DNS_ERR_EMPTY_LABEL, DNS_ERR_LABEL_LONG, DNS_ERR_NAME_LONG, DNS_ERR_NAME_BYTE or DNS_ERR_SPACE.

dnsParseReply

Reads msg[0, len) as the reply to query[0, queryLen), a query dnsBuildQuery wrote, into reply, with port written into every address.

Answers DNS_NOERROR, DNS_NXDOMAIN, DNS_SERVFAIL or DNS_REFUSED for a reply that answers the query, or a DNS_ERR_* code for one that is malformed or answers another. The answer records are read only under NOERROR and with TC clear; with TC set, reply.truncated says so, reply.count is 0 whatever the counts claim, and the caller asks again over TCP. The authority and additional sections are counted against the bytes left and never read. reply is reset first and written in place, so nothing is allocated; it holds this reply's answer until the next call.

const dnsParseReply: (
  msg: u8[],
  len: i32,
  query: u8[],
  queryLen: i32,
  port: i32,
  reply: DnsReply,
) => i32
msgu8[]required

The datagram (or TCP message, without its length) that came back.

leni32required

How many bytes of msg, from offset 0, are the reply; a length outside msg panics.

queryu8[]required

The query this reply should answer, as dnsBuildQuery wrote it: the reply's ID and question are compared with its bytes. A query under 12 bytes, or with another ID, answers DNS_ERR_ID; once the reply passes the ID, QR, opcode and QDCOUNT checks, a query whose question cannot be read back panics.

queryLeni32required

The query's length, as dnsBuildQuery answered it; a length outside query panics.

porti32required

The port, 0 to 0xFFFF, written big-endian into the last two bytes of every kept address; any other value panics.

replyDnsReplyrequired

The caller's reused DnsReply, reset and filled in.

returnsi32

The reply's RCODE when it answers the query (DNS_NOERROR, DNS_NXDOMAIN, DNS_SERVFAIL or DNS_REFUSED), with the addresses in reply only under DNS_NOERROR with reply.truncated clear; or a negative DNS_ERR_* code: DNS_ERR_RCODE for a reply to this query with any other RCODE (FORMERR, NOTIMP or one undefined), and the others for a reply that is malformed or answers another query.

Classes

DnsReply

One reply read by dnsParseReply, made once and reused.

The arrays are sized for DNS_MAX_ANSWERS, and owner and chain hold a name each in lowercase wire form, so reading a reply writes only into what the constructor made.

class DnsReply
Member
new DnsReply() Makes an empty reply with every array sized for DNS_MAX_ANSWERS answers and DNS_MAX_NAME_BYTES-byte names, for dnsParseReply to fill.
addresses: u8[] count addresses of DNS_ADDRESS_BYTES each, from offset 0.
count: i32 How many addresses were kept.
dropped: i32 How many addresses past DNS_MAX_ANSWERS were read and not kept.
rcode: i32 The reply's RCODE (0 to 15), once the reply was found to answer the query; 0 when it was refused before that.
truncated: boolean The TC bit: the reply was cut to fit a datagram, and no record of it was read.
ttls: i32[] The TTL of each kept address, in seconds; one above 2^31 - 1 reads as 0 (RFC 2181 §8).

Limits

8

DNS_MAX_ANSWERS: i32

How many addresses one reply keeps; the rest are counted in DnsReply.dropped.

63

DNS_MAX_LABEL_BYTES: i32

The longest label (RFC 1035 §2.3.4).

255

DNS_MAX_NAME_BYTES: i32

The longest name in wire form, its root byte included (RFC 1035 §2.3.4).

16

DNS_MAX_POINTER_HOPS: i32

How many compression pointers one name may follow.

DNS_​QUERY_​MAX_​BYTES

DNS_QUERY_MAX_BYTES: i32

The longest query dnsBuildQuery writes: the header, the longest name, the type and class.

Constants

18

DNS_ADDRESS_BYTES: i32

The bytes of one address: sixteen of IPv6 and two of port.

1

DNS_CLASS_IN: i32

The Internet class, the only one asked or kept.

-13

DNS_ERR_COUNT: i32

The reply's counts promise more records than its remaining bytes can hold.

-2

DNS_ERR_EMPTY_LABEL: i32

The name to ask is empty, or holds an empty label (a..b, .a).

-7

DNS_ERR_HEADER: i32

The reply is shorter than its 12-byte header.

-15

DNS_ERR_HOPS: i32

A name follows more than DNS_MAX_POINTER_HOPS compression pointers.

-10

DNS_ERR_ID: i32

The reply's ID is not the query's.

-3

DNS_ERR_LABEL_LONG: i32

A label of the name to ask is longer than 63 bytes.

-16

DNS_ERR_LABEL_TYPE: i32

A label's length byte starts with the bits 01 or 10, types RFC 6891 retired.

-5

DNS_ERR_NAME_BYTE: i32

The name to ask holds a byte that is not printable ASCII (a control byte, a space, or above 0x7E).

-4

DNS_ERR_NAME_LONG: i32

A name is longer than 255 bytes in wire form: the one to ask, or one in the reply.

-8

DNS_ERR_NOT_REPLY: i32

The reply's QR bit is clear: it is a query, not a reply.

-9

DNS_ERR_OPCODE: i32

The reply's opcode is not 0 (a standard query).

-14

DNS_ERR_POINTER: i32

A compression pointer points at or after the run of labels that holds it, or into the header.

-6

DNS_ERR_QTYPE: i32

The type to ask is not DNS_TYPE_A or DNS_TYPE_AAAA.

-11

DNS_ERR_QUESTION: i32

The reply does not hold exactly one question, or not the query's name, type and class.

-19

DNS_ERR_RCODE: i32

The reply's RCODE is none of NOERROR, SERVFAIL, NXDOMAIN and REFUSED (FORMERR, NOTIMP, or one undefined).

-18

DNS_ERR_RDATA: i32

A record's RDATA runs past the end of the reply, or a CNAME's target does not fill it.

-17

DNS_ERR_RDLENGTH: i32

An A record's RDLENGTH is not 4, or an AAAA record's is not 16.

-12

DNS_ERR_SHORT: i32

A name or a record's fixed fields run past the end of the reply.

-1

DNS_ERR_SPACE: i32

out has no room for the query; nothing is written past out.length.

0

DNS_NOERROR: i32

The server answered: the name exists, and its addresses, if any, are in the reply.

3

DNS_NXDOMAIN: i32

The name does not exist (RCODE 3).

5

DNS_REFUSED: i32

The server will not answer (RCODE 5).

2

DNS_SERVFAIL: i32

The server could not answer (RCODE 2).

1

DNS_TYPE_A: i32

The record type of an IPv4 address (RFC 1035 §3.2.2).

28

DNS_TYPE_AAAA: i32

The record type of an IPv6 address (RFC 3596 §2.1).

5

DNS_TYPE_CNAME: i32

The record type of an alias (RFC 1035 §3.2.2).