$pkt-id($id) $pkt-query($boolean) $pkt-operation_code($code) $pkt-is_authoritative($boolean) $pkt-is_truncated($boolean) $pkt-recursion_desired($boolean) $pkt-recursion_available($boolean) $pkt-response_code($code) $pkt-qdcount($count) $pkt-ancount($count) $pkt-nscount($count) $pkt-arcount($count) $pkt->rr_push($section, \%data) $pkt->rr_pop($section, $no_pop) $pkt->set_rr($section, \@RR) $pkt-get_rr($section)
RNA::DNS::Packet
use RNA::DNS::Packet;
my $pkt = new RNA::DNS::Packet();
$pkt->fill_buffer($packet_bytes);
$pkt->parse();
or
my $pkt = new RNA::DNS::Packet($packet_bytes);
$pkt->id(0x34);
send($socket, $pkt->prepare(), $pkt->size());
This module is part of the RNA Server, an implementation of DNA Project. DNA is an acronym for Domain Name Anarchy. For further informations take a look at DNA man page or browse http://www.dna-project.net/.
This module provide a full interface to DNS packet management, providing parsing, construction and so on.
Below we show all methods exported by RNA::DNS::Packet class. We distinguish between several areas like:
* Object Initialization
* Packet Parsing
* Packet Production
* Packet Statistics
* Pointers and Message Compression
* Data Queries and Updates
* Internal Methods
This section describes how to create a new RNA::DNS::Packet object.
RNA::DNS::Packet-new($packet,$debug_level) Create a new packet object. Data passwd through $packet scalar can be both raw data and structured data. $debug_level is an optional integer debug trigger. Setting to 0 will close explicitly debug output. If not provided, ``debug'' directive value is used.
$pkt-fill_buffer($packet) Set the raw content of the packet object without starting parsing
procedure. If you want to use later the object you'll need to call
$pkt->parse() but without need to pass any argument.
This section describe how packet parsing is done.
$pkt-check_internal_consistency() Called after $pkt-new() or $pkt-parse() , verify integrity
of data structures.
$pkt-parse($buffer) Elaborate a DNS packet and analyze its contents. Accept raw data coming from a DNS query. Returns a hash reference. Passing $buffer is optional if packet data has been feed to object on creation time with something like:
my $packet = new RNA::DNS::Packet( $binary );
$pkt-parse_rr($section) Parse Resource Records not of QD type (not question RR) Data in the packet are taken from $self->{buffer} and should be already cleaned of header section and of previous RR sections.
$section can be one of ``ANs'' for answers, ``NSs'' for name servers or ``ARs'' for additional resources. Is required for data storage.
Since AN, NS and AR Resource Records share the same scheme of data packaging, it's silly to cut'n'paste three time the same code.
$pkt->parse_rr_rdata($type, $class, $rdlength) Parse the content of an RDATA field inside a RESOURCE RECORD. Is mainly
called internally from parse_rr(). $type is the
type of the query, $class is the class of the query and $rdlength
is the total length of the RDATA field. No parameter can be omitted.
$type and $class can be passed in both numerical or mnemonic form.
Return a hash reference of a structure describing the RDATA field.
$pkt-parse_label() Consume $self->{buffer} until an entire label (terminated by 0x00 or by a pointer) has been parsed. Then return the label, such as ``www.ecn.org''.
Pay attention: since working on $self->{buffer} , each octect of the stream
can be read just one single time! If you discard label returned by
parse_label() you will not have a second chance to fetch the same label.
How to prepare a packet.
$pkt-prepare() Serialize the packet for net delivery.
$pkt-prepare_rr(\%data) Prepare a Resource Record to be sent. %data is a hash conforming to those created by parse_rr().
QD = (
qname => 'www.ecn.org',
qtype => 'A',
qclass => 'IN',
);
not_QD = (
name => 'www.ecn.org',
type => 'A',
class => 'IN',
ttl => 336750, # ....... Optional. Defaults to TTL directive.
rdlength => 4, # ....... Optional. Automatically calculated.
rdata => <IP ADDRESS>,
);
$pkt->prepare_rr_rdata( $data, $type, $class ) Prepare an answer for passed data in the style appropriate to $type and $class. $data is a scalar containing the data. $type is the query type expressed as mnemonic code ('A', 'NS', 'MX', 'SOA', ....). If $type is not provided, 'A' QTYPE is assumed. $class is the class type expressed as mnemonic code ('IN', 'CS', ...). If $class is not provided, 'IN' QCLASS is assumed.
Return two scalars containing a packed version of data and the length, already prepare for network transmission.
# TODO
#
# We need a generic mechanism to enable recursive
# construction of packet. For example, this case:
# we have a MX TYPE; we use ns.mydomain.net as
# rdata BUT we need an Additional Resource Record
# to specify also that ns.mydomain.net is 19.4.32.12,
# ok? So we need a mechanis to say to packet build
# NOW that we need a new RR of type XYZ...
#
# A good implementation can be this one: a stack,
# rappresented by a list of RR, is maintained by a
# main cycle which calls internally this function,
# passing both the RR to be packed and the stack.
# If this sub need to add a new RR # can simply push
# a new value at stack end.
#
# Last note: no! Recursive mechanism has not to be
# built inside this class. It's an outside decision
# to add or to omit a RR. The stack idea is always
# valid, but @ higher level, such DNS.pm module.
Some code to provide some packet related informations.
$pkt-contents() Print a digest of query header contents. It's only for debugging purposes.
$pkt-rr_table() Print out a synoptic table of all RRs.
$pkt-print_packet_raw_data() Print a formatted rappresentation of a raw packet in $self->{raw_packet} .
$pkt-size() Return the packet length, evaluated on most recent $self->{raw_packet} available. To ensure you have an updated size, use prepare() before using length().
How internal pointers are handled. Pointers are managed transparently in key methods like parse_label(), printable_domain_name(), prepare_domain_name(), and so on.
$pkt-get_pointers() Return a copy of complete pointers hash.
$pkt-set_pointers(\%data) Set explicitly the complete sequence of pointers.
$pkt->set_pointer($label, $pointer) Set explicitly the presence of label $label at position $pointer in the internal pointer database.
$pkt-find_pointer($label) Return a list of corresponding position of label $label if found in array $self->{pointers} .
$pkt-find_label($pointer) Return corresponding label to pointer $pointer if found in hash $self->{pointers} .
This subroutines are devoted to internal data query and manipulation.
$pkt-id($id) Get and optionally set packet ID field.
$pkt-query($boolean) Get and optionally set if the packet is a query packet (0) or an answer packet (1).
$pkt-operation_code($code) Get or set the query operation_code. Opcodes meaning is [from rfc 1035]:
0 .... a standard query
1 .... an inverse query
2 .... a server status request
3-15 reserved for future use
$pkt-is_authoritative($boolean) Return true if answer is authoritative, false otherwise. If a boolean parameter is passed, authoritativeness of the answer is set.
$pkt-is_truncated($boolean) Return true if packet is truncated, false otherwise. If a boolean parameter is passed, truncation of packet is set.
$pkt-recursion_desired($boolean) Get and optionally set recursion requirements.
$pkt-recursion_available($boolean) Get and optionally set recursion availability.
$pkt-response_code($code) Get or set the query response code. Codes meaning is [from rfc 1035]:
0 .... no error
1 .... format error: the name server was
unable to interpret the query
2 .... server failure: The name server was
unable to process this query due to a
problem with the name server.
3 .... Name Error - Meaningful only for
responses from an authoritative name
server, this code signifies that the
domain name referenced in the query does
not exist.
4 .... Not Implemented - The name server does
not support the requested kind of query.
5 .... Refused - The name server refuses to
perform the specified operation for
policy reasons. For example, a name
server may not wish to provide the
information to the particular requester,
or a name server may not wish to perform
a particular operation (e.g., zone
transfer) for particular data.
6-15 Reserved for future use.
$pkt-qdcount($count) Get and optionally set the numbert of QD records.
$pkt-ancount($count) Get and optionally set the numbert of AN records.
$pkt-nscount($count) Get and optionally set the numbert of NS records.
$pkt-arcount($count) Get and optionally set the numbert of AR records.
$pkt->rr_push($section, \%data) Add new Resource Record to section $section. Section can be one of ``QDs'', ``ARs'', ``NSs'', ``ARs''.
$pkt->rr_pop($section, $no_pop) Pop next Resource Record from section $section. Section can be one of ``QDs'', ``ARs'', ``NSs'', ``ARs''. If $no_pop is true, the value is not popped outside the pool.
$pkt->set_rr($section, \@RR) Set the entire pool of resource record for section $section. Section can
be one of ``QDs'', ``ARs'', ``NSs'', ``ARs''. For %RR format please refer to
$pkt->prepare_rr() back in this page.
$pkt-get_rr($section) Get the entire pool of resource record for section $section. Section can
be one of ``QDs'', ``ARs'', ``NSs'', ``ARs''. The pool is returned as array reference.
For pool format please refer to $pkt->prepare_rr() back in this page.
This methods are not useful (al least so far we thought about that ;-) outside this class.
$pkt-printable_domain_name($string) Return a printable version of a packed domain name as ``3www3ecn3org0''.
$pkt->prepare_domain_name($seq_of_labels, $add_pointer) Encoding domain names for packet delivery is a so common practice that split code into a separate subroutine make sense. $seq_of_labels is a scalar containing the domain name in human readable form, like ``www.strumentiresistenti.org''.
Return data ready to be injected into packet, comprensive of 0x00 terminator octect.
$add_pointer is a boolean attribute. If true, also call
$pkt->set_pointer() to add label to pointers hash.
$pkt->consume_buffer($octects, $dont_cut) consume_buffer() will consume as many octects from the internal buffer as is specified by the $octects argument. $dont_cut is a boolean flag which defaults to 0. If set to 1, octects will not be cut from buffer, and will be available for further readings.
consume_buffer() will also increment $self->{position} counter,
unless $dont_cut is true. If you use substr or other methods acting
directly on $self->{buffer} , you have to manually increment
$self->{position} . For this reason, we strongly suggest to use
consume_buffer() instead.
$pkt->grow_buffer($string1, $string2, ..., $stringN) Adds to internal buffer bytes passed as arguments. Also increments $self->{position} counter.
$pkt-position($index) Get or optionally set the position.
Written by Tx0 .
© 2003 Tx0
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Some practical programming solutions has been taken from Net::DNS modules by Michael Fuhr and others. For further information please see http://www.net-dns.org/ or the man page of Net::DNS.
RNA(5), RNA::Internals(3), RNA::Internode(3), rnad(8), Net::DNS(3), Net::DNS::Header(3)
This page last modified: Wednesday, 09-Jan-2008 16:25:00 CET
