net::dns+x86_64 +linux

dns: low-level DNS support and DNS resolver

net::dns implements low-level DNS message encoding and decoding, as well as a porcelain DNS resolver.

TODO:

Index

Types

type a;
type aaaa;
type caa;
type class;
type cname;
type dnskey;
type edns_opt;
type header;
type message;
type mx;
type ns;
type nsec;
type op;
type opcode;
type opt;
type ptr;
type qclass;
type qr;
type qtype;
type question;
type rcode;
type rdata;
type rrecord;
type rrsig;
type rtype;
type soa;
type srv;
type sshfp;
type tsig;
type txt;
type unknown_rdata;

Errors

type bad_key;
type bad_sig;
type bad_time;
type error;
type format;
type name_error;
type name_exists;
type not_auth;
type not_implemented;
type not_zone;
type refused;
type rrset_error;
type rrset_exists;
type server_failure;
type unknown_error;

Functions

fn decode(buf: []u8) (*message | format | nomem);
fn encode(buf: []u8, msg: *message) (size | error);
fn message_free(msg: *message) void;
fn parse_domain(in: str) ([]str | nomem);
fn query(query: *message, servers: ip::addr...) (*message | error | nomem);
fn strerror(err: error) str;
fn unparse_domain(in: []str) (str | nomem);

Types

type a[permalink] [source]

type a = ip::addr4;

An A record.

type aaaa[permalink] [source]

type aaaa = ip::addr6;

An AAAA record.

type caa[permalink] [source]

type caa = struct {
	flags: u8,
	tag: str,
	value: str,
};

A CAA record.

type class[permalink] [source]

type class = enum u16 {
	IN = 1,
	CS = 2,
	CH = 3,
	HS = 4,
};

Class type (e.g. Internet).

type cname[permalink] [source]

type cname = struct {
	name: []str,
};

A CNAME record.

type dnskey[permalink] [source]

type dnskey = struct {
	flags: u16,
	protocol: u8,
	algorithm: u8,
	key: []u8,
};

A DNSKEY record.

type edns_opt[permalink] [source]

type edns_opt = struct {
	code: u16,
	data: []u8,
};

An EDNS (RFC 6891) option, as contained in opt records. 

type header = struct {
	id: u16,
	op: op,
	// Number of questions
	qdcount: u16,
	// Number of answers
	ancount: u16,
	// Number of name servers
	nscount: u16,
	// Number of additional resources
	arcount: u16,
};

DNS message header.

type message[permalink] [source]

type message = struct {
	header: header,
	questions: []question,
	answers: []rrecord,
	authority: []rrecord,
	additional: []rrecord,
};

A DNS message, Hare representation. See encode and decode for the DNS representation.

type mx[permalink] [source]

type mx = struct {
	priority: u16,
	name: []str,
};

An MX record.

type ns[permalink] [source]

type ns = struct {
	name: []str,
};

An NS record.

type nsec[permalink] [source]

type nsec = struct {
	next_domain: []str,
	type_bitmaps: []u8,
};

An NSEC record.

type op[permalink] [source]

type op = struct {
	// Is this a query or a response?
	qr: qr,
	// Operation code
	opcode: opcode,
	// Authoritative answer bit
	aa: bool,
	// Truncation bit
	tc: bool,
	// Recursion desired bit
	rd: bool,
	// Recursion available bit
	ra: bool,
	// Response code
	rcode: rcode,
};

Operational information for this message.

type opcode[permalink] [source]

type opcode = enum u8 {
	QUERY = 0,
	IQUERY = 1,
	STATUS = 2,
	UPDATE = 5,
};

Operation requested from resolver.

type opt[permalink] [source]

type opt = struct {
	options: []edns_opt,
};

An OPT record (EDNS, RFC 6891).

type ptr[permalink] [source]

type ptr = struct {
	name: []str,
};

A PTR record.

type qclass[permalink] [source]

type qclass = enum u16 {
	IN = 1,
	CS = 2,
	CH = 3,
	HS = 4,
	NONE = 254, // *
	ANY = 255,
};

Query class (superset of class).

type qr[permalink] [source]

type qr = enum u8 {
	QUERY = 0,
	RESPONSE = 1,
};

Bit indicating if a header precedes a query or response.

type qtype[permalink] [source]

type qtype = enum u16 {
	A = 1,
	NS = 2,
	CNAME = 5,
	SOA = 6,
	PTR = 12,
	MX = 15,
	TXT = 16,
	AAAA = 28,
	SRV = 33,
	OPT = 41,
	SSHFP = 44,
	RRSIG = 46,
	NSEC = 47,
	DNSKEY = 48,
	AXFR = 252, // ...
	ALL = 255, // *
	CAA = 257,
};

Question type (superset of rtype).

type question[permalink] [source]

type question = struct {
	qname: []str,
	qtype: qtype,
	qclass: qclass,
};

A question section item.

type rcode[permalink] [source]

type rcode = enum u8 {
	NOERROR = 0,
	FORMERR = 1,
	SERVFAIL = 2,
	NXDOMAIN = 3,
	NOTIMP = 4,
	REFUSED = 5,
	YXDOMAIN = 6, // RFC 2136 UPDATE
	YXRRSET = 7,
	NXRRSET = 8,
	NOTAUTH = 9,
	NOTZONE = 10,
	BADSIG = 16, // RFC 2845 TSIG
	BADKEY = 17,
	BADTIME = 18,
};

Response code from resolver.

type rdata[permalink] [source]

type rdata = (a | aaaa | caa | cname | dnskey | mx | ns | nsec | opt | ptr | rrsig | soa | srv | sshfp | tsig | txt | unknown_rdata);

Tagged union of supported rdata types.

type rrecord[permalink] [source]

type rrecord = struct {
	name: []str,
	rtype: rtype,
	class: class,
	ttl: u32,
	rdata: rdata,
};

A resource record item.

type rrsig[permalink] [source]

type rrsig = struct {
	type_covered: u16,
	algorithm: u8,
	labels: u8,
	orig_ttl: u32,
	sig_expiration: u32,
	sig_inception: u32,
	key_tag: u16,
	signer_name: []str,
	signature: []u8,
};

An RRSIG record.

type rtype[permalink] [source]

type rtype = enum u16 {
	A = 1,
	NS = 2,
	CNAME = 5,
	SOA = 6,
	PTR = 12,
	MX = 15,
	TXT = 16,
	AAAA = 28,
	SRV = 33,
	OPT = 41,
	SSHFP = 44,
	RRSIG = 46,
	NSEC = 47,
	DNSKEY = 48,
	TSIG = 250,
	CAA = 257,
};

Record type.

type soa[permalink] [source]

type soa = struct {
	mname: []str,
	rname: []str,
	serial: u32,
	refresh: u32,
	retry: u32,
	expire: u32,
};

An SOA record.

type srv[permalink] [source]

type srv = struct {
	priority: u16,
	weight: u16,
	port: u16,
	target: []str,
};

An SRV record.

type sshfp[permalink] [source]

type sshfp = struct {
	algorithm: u8,
	fp_type: u8,
	fingerprint: []u8,
};

An SSHFP record.

type tsig[permalink] [source]

type tsig = struct {
	algorithm: []str,
	time_signed: u64,
	fudge: u16,
	mac_len: u16,
	mac: []u8,
	orig_id: u16,
	error: u16,
	other_len: u16,
	other_data: []u8,
};

A TSIG record.

type txt[permalink] [source]

type txt = [][]u8;

A TXT record.

type unknown_rdata[permalink] [source]

type unknown_rdata = []u8;

The raw rdata field for an rrecord with an unknown rtype.

Errors

type bad_key[permalink] [source]

type bad_key = !void;

Key not recognized.

type bad_sig[permalink] [source]

type bad_sig = !void;

TSIG signature validation failed.

type bad_time[permalink] [source]

type bad_time = !void;

Signature out of time window.

type error[permalink] [source]

type error = !(format | server_failure | name_error | not_implemented | refused | name_exists | rrset_exists | rrset_error | not_auth | not_zone | bad_sig | bad_key | bad_time | unknown_error | errors::invalid | errors::overflow | errors::timeout | net::error | io::error);

All error types which might be returned from functions in this module.

type format[permalink] [source]

type format = !void;

The DNS message was poorly formatted.

type name_error[permalink] [source]

type name_error = !void;

The domain name referenced in the query does not exist. Meaningful only for responses from an authoritative name server.

type name_exists[permalink] [source]

type name_exists = !void;

Dynamic update prerequisite unsatisfied: a domain name exists when it shouldn't.

type not_auth[permalink] [source]

type not_auth = !void;

Server not authoritative for the zone or request not authorized.

type not_implemented[permalink] [source]

type not_implemented = !void;

The name server does not support the requested kind of query.

type not_zone[permalink] [source]

type not_zone = !void;

Name not contained in zone.

type refused[permalink] [source]

type refused = !void;

The name server refuses to perform the specified operation for policy reasons.

type rrset_error[permalink] [source]

type rrset_error = !void;

Dynamic update prerequisite unsatisfied: a resource record set doesn't exists when it should.

type rrset_exists[permalink] [source]

type rrset_exists = !void;

Dynamic update prerequisite unsatisfied: a resource record set exists when it shouldn't.

type server_failure[permalink] [source]

type server_failure = !void;

The name server was unable to process this query due to a problem with the name server.

type unknown_error[permalink] [source]

type unknown_error = !u8;

Any other server-provided error condition not known to Hare.

Functions

fn decode[permalink] [source]

fn decode(buf: []u8) (*message | format | nomem);

Decodes a DNS message, heap allocating the resources necessary to represent it in Hare's type system. The caller must use message_free to free the return value.

fn encode[permalink] [source]

fn encode(buf: []u8, msg: *message) (size | error);

Encodes a DNS message, returning its size, or an error.

fn message_free[permalink] [source]

fn message_free(msg: *message) void;

Frees a message and the resources associated with it.

fn parse_domain[permalink] [source]

fn parse_domain(in: str) ([]str | nomem);

Converts a human-readable domain name (e.g. "example.org") into a DNS-ready name slice (e.g. ["example", "org"]). The slice returned must be freed by the caller, but the members of the slice themselves are borrowed from the input.

fn query[permalink] [source]

fn query(query: *message, servers: ip::addr...) (*message | error | nomem);

Performs a DNS query using the provided list of DNS servers. The caller must free the return value with message_free.

If no DNS servers are provided, the system default servers (if any) are used.

fn strerror[permalink] [source]

fn strerror(err: error) str;

Converts an error into a human-friendly string. The result may be statically allocated.

fn unparse_domain[permalink] [source]

fn unparse_domain(in: []str) (str | nomem);

Converts a DNS name slice (e.g. ["example", "org"]) into a human-readable domain name (e.g. "example.org"). The return value must be freed by the caller.