.\" Copyright (c) 2018-2022, OARC, Inc.
.\" All rights reserved.
.\"
.\" This file is part of dnsjit.
.\"
.\" dnsjit is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" dnsjit is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with dnsjit.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH dnsjit.core.object.dns 3 "1.2.3" "dnsjit"
.SH NAME
dnsjit.core.object.dns \- Container of a DNS message
.SH SYNOPSIS
.SS Parse DNS header and check if query or response
  local dns = require("dnsjit.core.object.dns").new(payload)
  if dns:parse_header() == 0 then
    if dns.qr == 0 then
      print(dns.id, dns.opcode_tostring(dns.opcode))
    else
      print(dns.id, dns.rcode_tostring(dns.rcode))
    end
  end
.SS Print a DNS payload
  local dns = require("dnsjit.core.object.dns").new(payload)
  dns:print()
.SS Parse a DNS payload
  local dns = require("dnsjit.core.object.dns").new(payload)
  local qs, q_labels, rrs, rr_labels = dns:parse()
  if qs and q_labels then
    ...
    if rrs and rr_labels then
      ...
    end
  end
.SH DESCRIPTION
The object that describes a DNS message.
.SS Attributes
.TP
includes_dnslen
If non-zero then this indicates that the DNS length is included in the
payload (for example if the transport is TCP) and will affect parsing of it.
.TP
have_dnslen
Set if the dnslen was included in the payload and could be read.
.TP
have_id
Set if there is a DNS ID.
.TP
have_qr
Set if there is a QR flag.
.TP
have_opcode
Set if there is an OPCODE.
.TP
have_aa
Set if there is a AA flag.
.TP
have_tc
Set if there is a TC flag.
.TP
have_rd
Set if there is a RD flag.
.TP
have_ra
Set if there is a RA flag.
.TP
have_z
Set if there is a Z flag.
.TP
have_ad
Set if there is a AD flag.
.TP
have_cd
Set if there is a CD flag.
.TP
have_rcode
Set if there is a RCODE.
.TP
have_qdcount
Set if there is an QDCOUNT.
.TP
have_ancount
Set if there is an ANCOUNT.
.TP
have_nscount
Set if there is a NSCOUNT.
.TP
have_arcount
Set if there is an ARCOUNT.
.TP
dnslen
The DNS length found in the payload.
.TP
id
The DNS ID.
.TP
qr
The QR flag.
.TP
opcode
The OPCODE.
.TP
aa
The AA flag.
.TP
tc
The TC flag.
.TP
rd
The RD flag.
.TP
ra
The RA flag.
.TP
z
The Z flag.
.TP
ad
The AD flag.
.TP
cd
The CD flag.
.TP
rcode
The RCODE.
.TP
qdcount
The QDCOUNT.
.TP
ancount
The ANCOUNT.
.TP
nscount
The NSCOUNT.
.TP
arcount
The ARCOUNT.
.SS Constants
The following tables exists for DNS parameters, taken from
.I https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml
on the 2016-12-09.
.LP
.IR CLASS ,
.IR CLASS_STR ,
.IR TYPE ,
.IR TYPE_STR ,
.IR OPCODE ,
.IR OPCODE_STR ,
.IR RCODE ,
.IR RCODE_STR ,
.IR AFSDB ,
.IR AFSDB_STR ,
.IR DHCID ,
.IR DHCID_STR ,
.IR ENDS0 ,
.IR ENDS0_STR
.LP
The
.I *_STR
tables can be used to get a textual representation of the numbers, see also
.IR class_tostring() ,
.IR type_tostring() ,
.IR opcode_tostring() ,
.IR rcode_tostring() ,
.IR afsdb_tostring() ,
.I dhcid_tostring()
and
.IR edns0_tostring() .
.SS Functions
.TP
.BR Dns.new "(obj)"
Create a new DNS object, optionally on-top of another object.
.TP
.BR Dns:type "()"
Return the textual type of the object.
.TP
.BR Dns:prev "()"
Return the previous object.
.TP
.BR Dns:cast "()"
Cast the object to the underlining object module and return it.
.TP
.BR Dns:uncast "()"
Cast the object to the generic object module and return it.
.TP
.BR Dns:copy "()"
Make a copy of the object and return it.
.TP
.BR Dns:free "()"
Free the object, should only be used on copies or otherwise allocated.
.TP
.BR Dns:log "()"
Return the Log object to control logging of this module.
.TP
.BR Dns:parse_header "()"
Begin parsing the underlaying object, first the header is parsed then
optionally continue calling
.IR parse_q ()
for the number of questions (see
.IR qdcount ).
After that continue calling
.IR parse_rr ()
for the number of answers, authorities and additionals resource records
(see
.IR ancount ", "
.I nscount
and
.IR arcount ).
Returns 0 on success or negative integer on error which can be for
malformed or truncated DNS (-2) or if more space for labels is needed (-3).
.TP
.BR Dns:parse_q "(q, labels, num_labels)"
Parse the next resource record as a question.
Returns 0 on success or negative integer on error which can be for
malformed or truncated DNS (-2) or if more space for labels is needed (-3).
.TP
.BR Dns:parse_rr "(rr, labels, num_labels)"
Parse the next resource record.
Returns 0 on success or negative integer on error which can be for
malformed or truncated DNS (-2) or if more space for labels is needed (-3).
.TP
.BR Dns:parse "(num_labels)"
Begin parsing the underlaying object using
.IR parse_header "(), "
.IR parse_q ()
and
.IR parse_rr ().
The optional
.I num_labels
can be used to set a specific number of labels used for each question
and resource record (default 16).
Returns result code, an array of questions, an array of question labels,
an array of resource records and an array of resource records labels.
Result code is 0 on success or negative integer on error which can be for
malformed or truncated DNS (-2) or if more space for labels is needed (-3).
.TP
.BR Dns:print "(num_labels)"
Begin parsing the underlaying object using
.IR parse_header "(), "
.IR parse_q ()
and
.IR parse_rr (),
and print it's content.
The optional
.I num_labels
can be used to set a specific number of labels used for each question
and resource record (default 16).
.TP
.BR Dns.class_tostring "(class)"
Return the textual name for a class.
.TP
.BR Dns.type_tostring "(type)"
Return the textual name for a type.
.TP
.BR Dns.opcode_tostring "(opcode)"
Return the textual name for an opcode.
.TP
.BR Dns.rcode_tostring "(rcode)"
Return the textual name for a rcode.
.TP
.BR Dns.afsdb_tostring "(afsdb)"
Return the textual name for an afsdb subtype.
.TP
.BR Dns.dhcid_tostring "(dhcid)"
Return the textual name for a dhcid type.
.TP
.BR Dns.edns0_tostring "(edns0)"
Return the textual name for an EDNS0 OPT record.
.SH SEE ALSO
.BR dnsjit.core.object (3),
.BR dnsjit.core.object.payload (3),
.BR dnsjit.core.object.dns.label (3),
.BR dnsjit.core.object.dns.q (3),
.BR dnsjit.core.object.dns.rr (3)
.SH AUTHORS and CONTRIBUTORS
Jerry Lundström (DNS-OARC),
Tomáš Křížek (CZ.NIC),
Petr Špaček (ISC)
.LP
Maintained by DNS-OARC
.LP
.RS
.I https://www.dns-oarc.net/
.RE
.LP
.SH BUGS
For issues and feature requests please use:
.LP
.RS
\fIhttps://github.com/DNS-OARC/dnsjit/issues\fP
.RE
.LP
For question and help please use:
.LP
.RS
\fIadmin@dns-oarc.net\fP
.RE
.LP