.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::DNS::Packet 3pm"
.TH Net::DNS::Packet 3pm "2020-11-20" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::DNS::Packet \- DNS protocol packet
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::DNS::Packet;
\&
\&    $query = Net::DNS::Packet\->new( \*(Aqexample.com\*(Aq, \*(AqMX\*(Aq, \*(AqIN\*(Aq );
\&
\&    $reply = $resolver\->send( $query );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Net::DNS::Packet object represents a \s-1DNS\s0 protocol packet.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 2
\&    $packet = Net::DNS::Packet\->new( \*(Aqexample.com\*(Aq );
\&    $packet = Net::DNS::Packet\->new( \*(Aqexample.com\*(Aq, \*(AqMX\*(Aq, \*(AqIN\*(Aq );
\&
\&    $packet = Net::DNS::Packet\->new();
.Ve
.PP
If passed a domain, type, and class, \fBnew()\fR creates a Net::DNS::Packet
object which is suitable for making a \s-1DNS\s0 query for the specified
information.  The type and class may be omitted; they default to A
and \s-1IN.\s0
.PP
If called with an empty argument list, \fBnew()\fR creates an empty packet.
.PP
.Vb 3
\&    $packet = Net::DNS::Packet\->decode( \e$data );
\&    $packet = Net::DNS::Packet\->decode( \e$data, 1 );    # debug
\&    $packet = Net::DNS::Packet\->new( \e$data ... );
.Ve
.PP
If passed a reference to a scalar containing \s-1DNS\s0 packet data, a new
packet object is created by decoding the data.
The optional second boolean argument enables debugging output.
.PP
Returns undef if unable to create a packet object.
.PP
Decoding errors, including data corruption and truncation, are
collected in the $@ ($EVAL_ERROR) variable.
.PP
.Vb 1
\&    ( $packet, $length ) = Net::DNS::Packet\->decode( \e$data );
.Ve
.PP
If called in array context, returns a packet object and the number
of octets successfully decoded.
.PP
Note that the number of RRs in each section of the packet may differ
from the corresponding header value if the data has been truncated
or corrupted during transmission.
.SS "data"
.IX Subsection "data"
.Vb 2
\&    $data = $packet\->data;
\&    $data = $packet\->data( $size );
.Ve
.PP
Returns the packet data in binary format, suitable for sending as a
query or update request to a nameserver.
.PP
Truncation may be specified using a non-zero optional size argument.
.SS "header"
.IX Subsection "header"
.Vb 1
\&    $header = $packet\->header;
.Ve
.PP
Constructor method which returns a Net::DNS::Header object which
represents the header section of the packet.
.SS "edns"
.IX Subsection "edns"
.Vb 3
\&    $edns    = $packet\->edns;
\&    $version = $edns\->version;
\&    $UDPsize = $edns\->size;
.Ve
.PP
Auxiliary function which provides access to the \s-1EDNS\s0 protocol
extension \s-1OPT RR.\s0
.SS "reply"
.IX Subsection "reply"
.Vb 1
\&    $reply = $query\->reply( $UDPmax );
.Ve
.PP
Constructor method which returns a new reply packet.
.PP
The optional UDPsize argument is the maximum \s-1UDP\s0 packet size which
can be reassembled by the local network stack, and is advertised in
response to an \s-1EDNS\s0 query.
.SS "question, zone"
.IX Subsection "question, zone"
.Vb 1
\&    @question = $packet\->question;
.Ve
.PP
Returns a list of Net::DNS::Question objects representing the
question section of the packet.
.PP
In dynamic update packets, this section is known as \fBzone()\fR and
specifies the \s-1DNS\s0 zone to be updated.
.SS "answer, pre, prerequisite"
.IX Subsection "answer, pre, prerequisite"
.Vb 1
\&    @answer = $packet\->answer;
.Ve
.PP
Returns a list of Net::DNS::RR objects representing the answer
section of the packet.
.PP
In dynamic update packets, this section is known as \fBpre()\fR or
\&\fBprerequisite()\fR and specifies the RRs or RRsets which must or must
not preexist.
.SS "authority, update"
.IX Subsection "authority, update"
.Vb 1
\&    @authority = $packet\->authority;
.Ve
.PP
Returns a list of Net::DNS::RR objects representing the authority
section of the packet.
.PP
In dynamic update packets, this section is known as \fBupdate()\fR and
specifies the RRs or RRsets to be added or deleted.
.SS "additional"
.IX Subsection "additional"
.Vb 1
\&    @additional = $packet\->additional;
.Ve
.PP
Returns a list of Net::DNS::RR objects representing the additional
section of the packet.
.SS "print"
.IX Subsection "print"
.Vb 1
\&    $packet\->print;
.Ve
.PP
Prints the entire packet to the currently selected output filehandle
using the master file format mandated by \s-1RFC1035.\s0
.SS "string"
.IX Subsection "string"
.Vb 1
\&    print $packet\->string;
.Ve
.PP
Returns a string representation of the packet.
.SS "from"
.IX Subsection "from"
.Vb 1
\&    print "packet received from ", $packet\->from, "\en";
.Ve
.PP
Returns the \s-1IP\s0 address from which this packet was received.
This method will return undef for user-created packets.
.SS "size"
.IX Subsection "size"
.Vb 1
\&    print "packet size: ", $packet\->size, " octets\en";
.Ve
.PP
Returns the size of the packet in octets as it was received from a
nameserver.  This method will return undef for user-created packets
(use length($packet\->data) instead).
.SS "push"
.IX Subsection "push"
.Vb 3
\&    $ancount = $packet\->push( prereq => $rr );
\&    $nscount = $packet\->push( update => $rr );
\&    $arcount = $packet\->push( additional => $rr );
\&
\&    $nscount = $packet\->push( update => $rr1, $rr2, $rr3 );
\&    $nscount = $packet\->push( update => @rr );
.Ve
.PP
Adds RRs to the specified section of the packet.
.PP
Returns the number of resource records in the specified section.
.PP
Section names may be abbreviated to the first three characters.
.SS "unique_push"
.IX Subsection "unique_push"
.Vb 3
\&    $ancount = $packet\->unique_push( prereq => $rr );
\&    $nscount = $packet\->unique_push( update => $rr );
\&    $arcount = $packet\->unique_push( additional => $rr );
\&
\&    $nscount = $packet\->unique_push( update => $rr1, $rr2, $rr3 );
\&    $nscount = $packet\->unique_push( update => @rr );
.Ve
.PP
Adds RRs to the specified section of the packet provided that the
RRs are not already present in the same section.
.PP
Returns the number of resource records in the specified section.
.PP
Section names may be abbreviated to the first three characters.
.SS "pop"
.IX Subsection "pop"
.Vb 3
\&    my $rr = $packet\->pop( \*(Aqpre\*(Aq );
\&    my $rr = $packet\->pop( \*(Aqupdate\*(Aq );
\&    my $rr = $packet\->pop( \*(Aqadditional\*(Aq );
.Ve
.PP
Removes a single \s-1RR\s0 from the specified section of the packet.
.SS "sign_tsig"
.IX Subsection "sign_tsig"
.Vb 1
\&    $query = Net::DNS::Packet\->new( \*(Aqwww.example.com\*(Aq, \*(AqA\*(Aq );
\&
\&    $query\->sign_tsig(
\&                \*(AqKhmac\-sha512.example.+165+01018.private\*(Aq,
\&                fudge => 60
\&                );
\&
\&    $reply = $res\->send( $query );
\&
\&    $reply\->verify( $query ) || die $reply\->verifyerr;
.Ve
.PP
Attaches a \s-1TSIG\s0 resource record object, which will be used to sign
the packet (see \s-1RFC 2845\s0).
.PP
The \s-1TSIG\s0 record can be customised by optional additional arguments to
\&\fBsign_tsig()\fR or by calling the appropriate Net::DNS::RR::TSIG methods.
.PP
If you wish to create a \s-1TSIG\s0 record using a non-standard algorithm,
you will have to create it yourself.  In all cases, the \s-1TSIG\s0 name
must uniquely identify the key shared between the parties, and the
algorithm name must identify the signing function to be used with the
specified key.
.PP
.Vb 10
\&    $tsig = Net::DNS::RR\->new(
\&                name            => \*(Aqtsig.example\*(Aq,
\&                type            => \*(AqTSIG\*(Aq,
\&                algorithm       => \*(Aqcustom\-algorithm\*(Aq,
\&                key             => \*(Aq<base64 key text>\*(Aq,
\&                sig_function    => sub {
\&                                          my ($key, $data) = @_;
\&                                                ...
\&                                        }
\&                );
\&
\&    $query\->sign_tsig( $tsig );
.Ve
.PP
The historical simplified syntax is still available, but additional
options can not be specified.
.PP
.Vb 1
\&    $packet\->sign_tsig( $key_name, $key );
.Ve
.PP
The response to an inbound request is signed by presenting the request
in place of the key parameter.
.PP
.Vb 2
\&    $response = $request\->reply;
\&    $response\->sign_tsig( $request, @options );
.Ve
.PP
Multi-packet transactions are signed by chaining the \fBsign_tsig()\fR
calls together as follows:
.PP
.Vb 3
\&    $opaque  =  $packet1\->sign_tsig( \*(AqKexample.+165+13281.private\*(Aq );
\&    $opaque  =  $packet2\->sign_tsig( $opaque );
\&                $packet3\->sign_tsig( $opaque );
.Ve
.PP
The opaque intermediate object references returned during multi-packet
signing are not intended to be accessed by the end-user application.
Any such access is expressly forbidden.
.PP
Note that a \s-1TSIG\s0 record is added to every packet; this implementation
does not support the suppressed signature scheme described in \s-1RFC2845.\s0
.SS "verify and verifyerr"
.IX Subsection "verify and verifyerr"
.Vb 2
\&    $packet\->verify()           || die $packet\->verifyerr;
\&    $reply\->verify( $query )    || die $reply\->verifyerr;
.Ve
.PP
Verify \s-1TSIG\s0 signature of packet or reply to the corresponding query.
.PP
.Vb 3
\&    $opaque  =  $packet1\->verify( $query ) || die $packet1\->verifyerr;
\&    $opaque  =  $packet2\->verify( $opaque );
\&    $verifed =  $packet3\->verify( $opaque ) || die $packet3\->verifyerr;
.Ve
.PP
The opaque intermediate object references returned during multi-packet
\&\fBverify()\fR will be undefined (Boolean false) if verification fails.
Access to the object itself, if it exists, is expressly forbidden.
Testing at every stage may be omitted, which results in a \s-1BADSIG\s0 error
on the final packet in the absence of more specific information.
.SS "sign_sig0"
.IX Subsection "sign_sig0"
\&\s-1SIG0\s0 support is provided through the Net::DNS::RR::SIG class.
The requisite cryptographic components are not integrated into
Net::DNS but reside in the Net::DNS::SEC distribution available
from \s-1CPAN.\s0
.PP
.Vb 3
\&    $update = Net::DNS::Update\->new(\*(Aqexample.com\*(Aq);
\&    $update\->push( update => rr_add(\*(Aqfoo.example.com A 10.1.2.3\*(Aq));
\&    $update\->sign_sig0(\*(AqKexample.com+003+25317.private\*(Aq);
.Ve
.PP
Execution will be terminated if Net::DNS::SEC is not available.
.SS "verify \s-1SIG0\s0"
.IX Subsection "verify SIG0"
.Vb 2
\&    $packet\->verify( $keyrr )           || die $packet\->verifyerr;
\&    $packet\->verify( [$keyrr, ...] )    || die $packet\->verifyerr;
.Ve
.PP
Verify \s-1SIG0\s0 packet signature against one or more specified \s-1KEY\s0 RRs.
.SS "sigrr"
.IX Subsection "sigrr"
.Vb 1
\&    $sigrr = $packet\->sigrr() || die \*(Aqunsigned packet\*(Aq;
.Ve
.PP
The sigrr method returns the signature \s-1RR\s0 from a signed packet
or undefined if the signature is absent.
.SS "truncate"
.IX Subsection "truncate"
The truncate method takes a maximum length as argument and then tries
to truncate the packet and set the \s-1TC\s0 bit according to the rules of
\&\s-1RFC2181\s0 Section 9.
.PP
The smallest length limit that is honoured is 512 octets.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c)1997\-2000 Michael Fuhr.
.PP
Portions Copyright (c)2002\-2004 Chris Reinhardt.
.PP
Portions Copyright (c)2002\-2009 Olaf Kolkman
.PP
Portions Copyright (c)2007\-2019 Dick Franks
.PP
All rights reserved.
.SH "LICENSE"
.IX Header "LICENSE"
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of the author not be used in advertising
or publicity pertaining to distribution of the software without specific
prior written permission.
.PP
\&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl, Net::DNS, Net::DNS::Update, Net::DNS::Header,
Net::DNS::Question, Net::DNS::RR, Net::DNS::RR::TSIG,
\&\s-1RFC1035\s0 Section 4.1, \s-1RFC2136\s0 Section 2, \s-1RFC2845\s0