Skip to content

dnsimple/dns_erlang

Repository files navigation

dns_erlang

An Erlang DNS message library that supports most common record types, TSIG authenticated messages, EDNS0 and DNSSEC.

Usage

This library exposes types via include/dns.hrl, which in turn includes include/dns_terms.hrl and include/dns_records.hrl, as well as functions useful for constructing and deconstructing DNS packets with src/dns.erl

This is a library, not a DNS server. It is meant to be used by Erlang-based DNS servers for low level packet handling and RR processing.

If you'd like to see a full example of dns_erlang in use, please have a look at erldns.

Details

The following section explains what is contained in the library in greater detail.

dns_terms.hrl

This file defines various terms, defined as Erlang macros, that are used in DNS packets. It includes a term for each DNS type, including one term for the numeric value and one term for the binary version. For example:

-define(DNS_TYPE_A_NUMBER, 1).
-define(DNS_TYPE_A_BSTR, <<"A">>).
-define(DNS_TYPE_NS, ?DNS_TYPE_NS_NUMBER).

It also contains rcodes, opcodes, errcodes, etc.

dns_records.hrl

This file defines the record definitions for various Erlang record types that are useful for representing DNS constructs. For example, the dns_message record represents all of the elements that you would find in a single DNS message.

-record(dns_message, {id = dns:random_id() :: dns:message_id(),
		      qr = false :: 0..1 | boolean(),
		      oc = ?DNS_OPCODE_QUERY :: dns:opcode(),
		      aa = false :: 0..1 | boolean(),
		      tc = false :: 0..1 | boolean(),
		      rd = false :: 0..1 | boolean(),
		      ra = false :: 0..1 | boolean(),
		      ad = false :: 0..1 | boolean(),
		      cd = false :: 0..1 | boolean(),
		      rc = ?DNS_RCODE_NOERROR :: dns:rcode(),
		      qc = 0 :: 0..65535,
		      anc = 0 :: 0..65535,
		      auc = 0 :: 0..65535,
		      adc = 0 :: 0..65535,
		      questions = [] :: dns:questions(),
		      answers = [] :: dns:answers(),
		      authority = [] :: dns:authority(),
		      additional = [] :: dns:additional()}).

Each of the record fields in dns_message corresponds to the elements defined in section 4 of RFC 1035. For example, id corresponds to the message header field ID, which is defined as:

A 16 bit identifier assigned by the program that generates any kind of query. This identifier is copied the corresponding reply and can be used by the requester to match up replies to outstanding queries.

Other records defined include dns_query, which represents a single question in the #dns_message.questions field, dns_rr which corresponds to a single resource record (RR), which appears in the answers, authority, additional section of the dns_message, and so on.

Note that all support RR types must include a dns_rrdata_ record definition, used to store the parts of the RDATA for that RR type.

dns.erl

The dns module is the primary entry point for the functionality in this library. The module exports various types used in type specs, such as message(), which indicates a #dns_message record, query() which represents a single #dns_query record, questions(), which represents a list of queries, etc.

It also exports functions for encoding and decoding messages, TSIG supporting functions, and various utility functions for comparing domain names, converting domain names into different cases, converting to and from label lists, etc.

dns_record.erl

The dns_record module exports serialise and deserialise functions for serialising and deserialising messages. You will generally not use these functions directly, rather you will use the functions for encoding and decoding messages exported by dns.erl.

dns_record_info.erl

This module exports utility functions used to inspect records. You will generally not use these functions directly.

dnssec.erl

The dnssec module exports functions used for generating NSEC responses, signing and verifying RRSIGs, and adding keytags to DNSKEY records.

For example, the sign_rr/6 function can be given a collection of resource records, the signer name, keytag, signing algorithm, private key, and a collection of options and it will return a list of RRSIG records. Currently only DSA and RSA algorithms are supported for signing RRSETs.