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
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.
dnsParseReply
Reads msg[0, len) as the reply to query[0, queryLen), a query dnsBuildQuery wrote, into reply, with port written into every address.
DnsReply
One reply read by dnsParseReply, made once and reused.
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.
idi32requiredThe 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.
qtypei32requiredDNS_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[]requiredThe 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.
porti32requiredThe port, 0 to 0xFFFF, written big-endian into the last two bytes of every kept address; any other value panics.
replyDnsReplyrequiredThe 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).

