dns (dns_erlang v5.0.5)
View SourceThe 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/0, which indicates
a #dns_message{} record, query/0 which represents a single #dns_query{} record,
questions/0, 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.
Summary
Functions: parsing
Decode a binary DNS message.
Decode a binary DNS query message with strict header validation.
Encode a message/0 record.
Encode a dns_message record - will truncate the message as needed.
Functions: TSIG
Generates and then appends a TSIG RR to a message.
Verifies a TSIG message signature.
Functions: utilities
Returns a random integer suitable for use as DNS message identifier.
Return current unix time in seconds.
Return the unix time in seconds from a timestamp or universal time.
Types: integer codes
DNS Message class. See RFC 1035: §4.1.2.
Decoding errors.
DNS Message ID. See RFC 1035: §4.1.1.
DNS opcode. See RFC 1035: §4.1.1.
DNS Return code. See RFC 1035: §4.1.1.
DNS Message class. See RFC 1035: §4.1.3.
DNS Message class. See RFC 1035: §4.1.2.
Unsigned 2-bits integer
Unsigned 4-bits integer
Unsigned 8-bits integer
Unsigned 16-bits integer
Unsigned 32-bits integer
Unsigned 48-bits integer
Unsigned 64-bits integer
Unix timestamp in seconds.
Types: records
Main DNS message structure.
Functions: parsing
-spec decode_message(message_bin()) -> {decode_error(), message() | undefined, binary()} | message().
Decode a binary DNS message.
-spec decode_query(message_bin()) -> {decode_error(), message() | undefined, binary()} | message().
Decode a binary DNS query message with strict header validation.
Performs header guard checks before decoding the message body to prevent DoS attacks. For standard queries (opcode 0), validates that:
- ANCount = 0 (queries should not have answers)
- NSCount = 0 (queries should not have authority records)
- QDCount = 1 (standard queries must have exactly one question)
For NOTIFY (opcode 4) and UPDATE (opcode 5), allows decoding to proceed. For other opcodes, falls back to standard decoding.
-spec encode_message(message()) -> message_bin().
Encode a message/0 record.
-spec encode_message(message(), encode_message_opts()) -> message_bin() | {message_bin(), tsig_mac()} | {truncated, message_bin(), message()} | {truncated, message_bin(), tsig_mac(), message()}.
Encode a dns_message record - will truncate the message as needed.
Functions: TSIG
Equivalent to add_tsig(Msg, Alg, Name, Secret, ErrCode, #{name => Name, alg => Alg}).
-spec add_tsig(message(), tsig_alg(), dname(), binary(), tsig_error(), encode_tsig_opts()) -> message().
Generates and then appends a TSIG RR to a message.
Supports MD5, SHA1, SHA224, SHA256, SHA384 and SHA512 algorithms.
-spec verify_tsig(message_bin(), dname(), binary()) -> {ok, tsig_mac()} | {error, tsig_error()}.
Equivalent to verify_tsig(MsgBin, Name, Secret, #{}).
-spec verify_tsig(message_bin(), dname(), binary(), tsig_opts()) -> {ok, tsig_mac()} | {error, tsig_error()}.
Verifies a TSIG message signature.
Functions: utilities
-spec random_id() -> message_id().
Returns a random integer suitable for use as DNS message identifier.
-spec unix_time() -> unix_time().
Return current unix time in seconds.
-spec unix_time(erlang:timestamp() | calendar:datetime1970()) -> unix_time().
Return the unix time in seconds from a timestamp or universal time.
Types: integer codes
-type class() :: uint16().
DNS Message class. See RFC 1035: §4.1.2.
-type decode_error() :: formerr | truncated | notimp | trailing_garbage.
Decoding errors.
Can be one of the following:
formerr: the message was malformed.truncated: the message was partially decoded, as data was found missing from the message.trailing_garbage: the message was successfully decoded, but there was trailing garbage at the end of the message.notimp: the opcode is not implemented (e.g., IQUERY, STATUS, DSO). The message struct contains minimal fields needed to construct a NOTIMP response.
-type eoptcode() :: uint16().
-type ercode() :: 0 | 16.
-type llqerrcode() :: 0..6.
-type llqopcode() :: 1..3.
-type message_id() :: uint16().
DNS Message ID. See RFC 1035: §4.1.1.
-type opcode() :: uint4().
DNS opcode. See RFC 1035: §4.1.1.
-type rcode() :: uint4().
DNS Return code. See RFC 1035: §4.1.1.
-type ttl() :: 0..1 bsl 31 - 1.
DNS Message class. See RFC 1035: §4.1.3.
-type type() :: uint16().
DNS Message class. See RFC 1035: §4.1.2.
-type uint2() :: 0..1.
Unsigned 2-bits integer
-type uint4() :: 0..15.
Unsigned 4-bits integer
-type uint8() :: 0..1 bsl 8 - 1.
Unsigned 8-bits integer
-type uint16() :: 0..1 bsl 16 - 1.
Unsigned 16-bits integer
-type uint32() :: 0..1 bsl 32 - 1.
Unsigned 32-bits integer
-type uint48() :: 0..1 bsl 48 - 1.
Unsigned 48-bits integer
-type uint64() :: 0..1 bsl 64 - 1.
Unsigned 64-bits integer
-type unix_time() :: 0..4294967295.
Unix timestamp in seconds.
Types: options
Types: records
-type answers() :: [rr()].
-type authority() :: [rr()].
-type message() :: #dns_message{id :: dns:message_id(), qr :: boolean(), oc :: dns:opcode(), aa :: boolean(), tc :: boolean(), rd :: boolean(), ra :: boolean(), ad :: boolean(), cd :: boolean(), rc :: dns:rcode(), qc :: dns:uint16(), anc :: dns:uint16(), auc :: dns:uint16(), adc :: dns:uint16(), questions :: dns:questions(), answers :: dns:answers(), authority :: dns:authority(), additional :: dns:additional()}.
Main DNS message structure.
-type opt_cookie() :: #dns_opt_cookie{client :: <<_:64>>, server :: undefined | <<_:64, _:_*8>>}.
-type opt_ecs() :: #dns_opt_ecs{family :: dns:uint16(), source_prefix_length :: dns:uint8(), scope_prefix_length :: dns:uint8(), address :: binary()}.
-type opt_ede() :: #dns_opt_ede{info_code :: dns:uint16(), extra_text :: binary()}.
-type opt_llq() :: #dns_opt_llq{opcode :: dns:uint16(), errorcode :: dns:uint16(), id :: dns:uint64(), leaselife :: dns:uint32()}.
-type opt_nsid() :: #dns_opt_nsid{data :: binary()}.
-type opt_owner() :: #dns_opt_owner{seq :: dns:uint8(), primary_mac :: <<_:48>>, wakeup_mac :: <<>> | <<_:48>>, password :: <<>> | <<_:48>>}.
-type opt_ul() :: #dns_opt_ul{lease :: dns:uint32()}.
-type optrr() :: #dns_optrr{udp_payload_size :: dns:uint16(), ext_rcode :: dns:uint8(), version :: dns:uint8(), dnssec :: boolean(), data :: [dns:optrr_elem()]}.
-type optrr_elem() :: opt_nsid() | opt_ul() | opt_unknown() | opt_ecs() | opt_llq() | opt_owner() | opt_cookie() | opt_ede().
-type questions() :: [query()].
-type records() :: additional() | answers() | authority() | questions().
-type rr() :: #dns_rr{name :: dns:dname(), type :: dns:type(), class :: dns:class(), ttl :: dns:ttl(), data :: dns:rrdata()}.
-type rrdata() :: binary() | #dns_rrdata_a{ip :: inet:ip4_address()} | #dns_rrdata_aaaa{ip :: inet:ip6_address()} | #dns_rrdata_afsdb{subtype :: dns:uint16(), hostname :: dns:dname()} | #dns_rrdata_caa{flags :: dns:uint8(), tag :: binary(), value :: binary()} | #dns_rrdata_cdnskey{flags :: dns:uint16(), protocol :: dns:uint8(), alg :: dns:uint8(), public_key :: iodata(), keytag :: integer()} | #dns_rrdata_cds{keytag :: dns:uint16(), alg :: dns:uint8(), digest_type :: dns:uint8(), digest :: binary()} | #dns_rrdata_cert{type :: dns:uint16(), keytag :: dns:uint16(), alg :: dns:uint8(), cert :: binary()} | #dns_rrdata_cname{dname :: dns:dname()} | #dns_rrdata_dhcid{data :: binary()} | #dns_rrdata_dlv{keytag :: dns:uint16(), alg :: dns:uint8(), digest_type :: dns:uint8(), digest :: binary()} | #dns_rrdata_dname{dname :: dns:dname()} | #dns_rrdata_eui48{address :: <<_:48>>} | #dns_rrdata_eui64{address :: <<_:64>>} | #dns_rrdata_dnskey{flags :: dns:uint16(), protocol :: dns:uint8(), alg :: dns:uint8(), public_key :: iodata(), keytag :: integer()} | #dns_rrdata_ds{keytag :: dns:uint16(), alg :: dns:uint8(), digest_type :: dns:uint8(), digest :: binary()} | #dns_rrdata_hinfo{cpu :: binary(), os :: binary()} | #dns_rrdata_ipseckey{precedence :: dns:uint8(), alg :: dns:uint8(), gateway :: dns:dname() | inet:ip_address(), public_key :: binary()} | #dns_rrdata_key{type :: dns:uint2(), xt :: 0..1, name_type :: dns:uint2(), sig :: dns:uint4(), protocol :: dns:uint8(), alg :: dns:uint8(), public_key :: binary()} | #dns_rrdata_kx{preference :: dns:uint16(), exchange :: dns:dname()} | #dns_rrdata_loc{size :: integer(), horiz :: integer(), vert :: integer(), lat :: dns:uint32(), lon :: dns:uint32(), alt :: dns:uint32()} | #dns_rrdata_mb{madname :: dns:dname()} | #dns_rrdata_mg{madname :: dns:dname()} | #dns_rrdata_minfo{rmailbx :: dns:dname(), emailbx :: dns:dname()} | #dns_rrdata_mr{newname :: dns:dname()} | #dns_rrdata_mx{preference :: dns:uint16(), exchange :: dns:dname()} | #dns_rrdata_naptr{order :: dns:uint16(), preference :: dns:uint16(), flags :: binary(), services :: binary(), regexp :: binary(), replacement :: dns:dname()} | #dns_rrdata_ns{dname :: dns:dname()} | #dns_rrdata_nsec{next_dname :: dns:dname(), types :: [non_neg_integer()]} | #dns_rrdata_nsec3{hash_alg :: dns:uint8(), opt_out :: boolean(), iterations :: dns:uint16(), salt :: binary(), hash :: binary(), types :: [non_neg_integer()]} | #dns_rrdata_nsec3param{hash_alg :: dns:uint8(), flags :: dns:uint8(), iterations :: dns:uint16(), salt :: binary()} | #dns_rrdata_nxt{dname :: dns:dname(), types :: [non_neg_integer()]} | #dns_rrdata_csync{soa_serial :: dns:uint32(), flags :: dns:uint16(), types :: [non_neg_integer()]} | #dns_rrdata_dsync{rrtype :: dns:uint16(), scheme :: dns:uint8(), port :: dns:uint16(), target :: dns:dname()} | #dns_rrdata_openpgpkey{data :: binary()} | #dns_rrdata_ptr{dname :: dns:dname()} | #dns_rrdata_rp{mbox :: dns:dname(), txt :: dns:dname()} | #dns_rrdata_rrsig{type_covered :: dns:uint16(), alg :: 3 | 5 | 6 | 7 | 8 | 10 | 13 | 14 | 15 | 16, labels :: dns:uint8(), original_ttl :: dns:uint32(), expiration :: dns:uint32(), inception :: dns:uint32(), keytag :: dns:uint16(), signers_name :: dns:dname(), signature :: binary()} | #dns_rrdata_rt{preference :: dns:uint16(), host :: dns:dname()} | #dns_rrdata_soa{mname :: dns:dname(), rname :: dns:dname(), serial :: dns:uint32(), refresh :: dns:uint32(), retry :: dns:uint32(), expire :: dns:uint32(), minimum :: dns:uint32()} | #dns_rrdata_spf{spf :: [binary()]} | #dns_rrdata_srv{priority :: dns:uint16(), weight :: dns:uint16(), port :: dns:uint16(), target :: dns:dname()} | #dns_rrdata_svcb{svc_priority :: dns:uint16(), target_name :: dns:dname(), svc_params :: dns:svcb_svc_params()} | #dns_rrdata_https{svc_priority :: dns:uint16(), target_name :: dns:dname(), svc_params :: dns:svcb_svc_params()} | #dns_rrdata_sshfp{alg :: dns:uint8(), fp_type :: dns:uint8(), fp :: binary()} | #dns_rrdata_tlsa{usage :: dns:uint8(), selector :: dns:uint8(), matching_type :: dns:uint8(), certificate :: binary()} | #dns_rrdata_smimea{usage :: dns:uint8(), selector :: dns:uint8(), matching_type :: dns:uint8(), certificate :: binary()} | #dns_rrdata_tsig{alg :: dns:tsig_alg(), time :: dns:uint48(), fudge :: dns:uint16(), mac :: binary(), msgid :: dns:uint16(), err :: dns:uint16(), other :: binary()} | #dns_rrdata_txt{txt :: [binary()]} | #dns_rrdata_uri{priority :: dns:uint16(), weight :: dns:uint16(), target :: binary()} | #dns_rrdata_resinfo{data :: [binary()]} | #dns_rrdata_wallet{data :: binary()} | #dns_rrdata_zonemd{serial :: dns:uint32(), scheme :: dns:uint8(), algorithm :: dns:uint8(), hash :: binary()}.
-type rrdata_rrsig() :: #dns_rrdata_rrsig{type_covered :: dns:uint16(), alg :: 3 | 5 | 6 | 7 | 8 | 10 | 13 | 14 | 15 | 16, labels :: dns:uint8(), original_ttl :: dns:uint32(), expiration :: dns:uint32(), inception :: dns:uint32(), keytag :: dns:uint16(), signers_name :: dns:dname(), signature :: binary()}.
Types: strings
-type dname() :: binary().
Domain name, expressed as a sequence of label/0, as defined in RFC 1035: §3.1.
-type label() :: binary().
DNS labels. See RFC 1035: §2.3.1.
The labels must follow the rules for ARPANET host names. They must start with a letter, end with a letter or digit, and have as interior characters only letters, digits, and hyphen. There are also some restrictions on the length. Labels must be 63 characters or less.
-type labels() :: [label()].
A list of dns:label/0
-type message_bin() :: <<_:96, _:_*8>>.
DNS wire message format.
The general form is a 96bits header, followed by a variable number of questions, answers, authorities, and additional records.