Net::DNS::Packet(3pm)

1Net::DNS::Packet(3)   User Contributed Perl Documentation  Net::DNS::Packet(3)
2
3
4

NAME

6       Net::DNS::Packet - DNS protocol packet
7

SYNOPSIS

9           use Net::DNS::Packet;
10
11           $query = Net::DNS::Packet->new( 'example.com', 'MX', 'IN' );
12
13           $reply = $resolver->send( $query );
14

DESCRIPTION

16       A Net::DNS::Packet object represents a DNS protocol packet.
17

METHODS

19   new
20           $packet = Net::DNS::Packet->new( 'example.com' );
21           $packet = Net::DNS::Packet->new( 'example.com', 'MX', 'IN' );
22
23           $packet = Net::DNS::Packet->new();
24
25       If passed a domain, type, and class, new() creates a Net::DNS::Packet
26       object which is suitable for making a DNS query for the specified
27       information.  The type and class may be omitted; they default to A and
28       IN.
29
30       If called with an empty argument list, new() creates an empty packet.
31
32           $packet = Net::DNS::Packet->decode( \$data );
33           $packet = Net::DNS::Packet->decode( \$data, 1 );    # debug
34           $packet = Net::DNS::Packet->new( \$data ... );
35
36       If passed a reference to a scalar containing DNS packet data, a new
37       packet object is created by decoding the data.  The optional second
38       boolean argument enables debugging output.
39
40       Returns undef if unable to create a packet object.
41
42       Decoding errors, including data corruption and truncation, are
43       collected in the $@ ($EVAL_ERROR) variable.
44
45           ( $packet, $length ) = Net::DNS::Packet->decode( \$data );
46
47       If called in array context, returns a packet object and the number of
48       octets successfully decoded.
49
50       Note that the number of RRs in each section of the packet may differ
51       from the corresponding header value if the data has been truncated or
52       corrupted during transmission.
53
54   data
55           $data = $packet->data;
56           $data = $packet->data( $size );
57
58       Returns the packet data in binary format, suitable for sending as a
59       query or update request to a nameserver.
60
61       Truncation may be specified using a non-zero optional size argument.
62
63   header
64           $header = $packet->header;
65
66       Constructor method which returns a Net::DNS::Header object which
67       represents the header section of the packet.
68
69   edns
70           $edns    = $packet->edns;
71           $version = $edns->version;
72           $UDPsize = $edns->size;
73
74       Auxiliary function which provides access to the EDNS protocol extension
75       OPT RR.
76
77   reply
78           $reply = $query->reply( $UDPmax );
79
80       Constructor method which returns a new reply packet.
81
82       The optional UDPsize argument is the maximum UDP packet size which can
83       be reassembled by the local network stack, and is advertised in
84       response to an EDNS query.
85
86   question, zone
87           @question = $packet->question;
88
89       Returns a list of Net::DNS::Question objects representing the question
90       section of the packet.
91
92       In dynamic update packets, this section is known as zone() and
93       specifies the DNS zone to be updated.
94
95   answer, pre, prerequisite
96           @answer = $packet->answer;
97
98       Returns a list of Net::DNS::RR objects representing the answer section
99       of the packet.
100
101       In dynamic update packets, this section is known as pre() or
102       prerequisite() and specifies the RRs or RRsets which must or must not
103       preexist.
104
105   authority, update
106           @authority = $packet->authority;
107
108       Returns a list of Net::DNS::RR objects representing the authority
109       section of the packet.
110
111       In dynamic update packets, this section is known as update() and
112       specifies the RRs or RRsets to be added or deleted.
113
114   additional
115           @additional = $packet->additional;
116
117       Returns a list of Net::DNS::RR objects representing the additional
118       section of the packet.
119
120   print
121           $packet->print;
122
123       Prints the entire packet to the currently selected output filehandle
124       using the master file format mandated by RFC1035.
125
126   string
127           print $packet->string;
128
129       Returns a string representation of the packet.
130
131   from
132           print "packet received from ", $packet->from, "\n";
133
134       Returns the IP address from which this packet was received.  This
135       method will return undef for user-created packets.
136
137   size
138           print "packet size: ", $packet->size, " octets\n";
139
140       Returns the size of the packet in octets as it was received from a
141       nameserver.  This method will return undef for user-created packets
142       (use length($packet->data) instead).
143
144   push
145           $ancount = $packet->push( prereq => $rr );
146           $nscount = $packet->push( update => $rr );
147           $arcount = $packet->push( additional => $rr );
148
149           $nscount = $packet->push( update => $rr1, $rr2, $rr3 );
150           $nscount = $packet->push( update => @rr );
151
152       Adds RRs to the specified section of the packet.
153
154       Returns the number of resource records in the specified section.
155
156       Section names may be abbreviated to the first three characters.
157
158   unique_push
159           $ancount = $packet->unique_push( prereq => $rr );
160           $nscount = $packet->unique_push( update => $rr );
161           $arcount = $packet->unique_push( additional => $rr );
162
163           $nscount = $packet->unique_push( update => $rr1, $rr2, $rr3 );
164           $nscount = $packet->unique_push( update => @rr );
165
166       Adds RRs to the specified section of the packet provided that the RRs
167       are not already present in the same section.
168
169       Returns the number of resource records in the specified section.
170
171       Section names may be abbreviated to the first three characters.
172
173   pop
174           my $rr = $packet->pop( 'pre' );
175           my $rr = $packet->pop( 'update' );
176           my $rr = $packet->pop( 'additional' );
177
178       Removes a single RR from the specified section of the packet.
179
180   sign_tsig
181           $query = Net::DNS::Packet->new( 'www.example.com', 'A' );
182
183           $query->sign_tsig(
184                       $keyfile,
185                       fudge => 60
186                       );
187
188           $reply = $res->send( $query );
189
190           $reply->verify( $query ) || die $reply->verifyerr;
191
192       Attaches a TSIG resource record object, which will be used to sign the
193       packet (see RFC 2845).
194
195       The TSIG record can be customised by optional additional arguments to
196       sign_tsig() or by calling the appropriate Net::DNS::RR::TSIG methods.
197
198       If you wish to create a TSIG record using a non-standard algorithm, you
199       will have to create it yourself.  In all cases, the TSIG name must
200       uniquely identify the key shared between the parties, and the algorithm
201       name must identify the signing function to be used with the specified
202       key.
203
204           $tsig = Net::DNS::RR->new(
205                       name            => 'tsig.example',
206                       type            => 'TSIG',
207                       algorithm       => 'custom-algorithm',
208                       key             => '<base64 key text>',
209                       sig_function    => sub {
210                                                 my ($key, $data) = @_;
211                                                       ...
212                                               }
213                       );
214
215           $query->sign_tsig( $tsig );
216
217       The response to an inbound request is signed by presenting the request
218       in place of the key parameter.
219
220           $response = $request->reply;
221           $response->sign_tsig( $request, @options );
222
223       Multi-packet transactions are signed by chaining the sign_tsig() calls
224       together as follows:
225
226           $opaque  =  $packet1->sign_tsig( 'Kexample.+165+13281.private' );
227           $opaque  =  $packet2->sign_tsig( $opaque );
228                       $packet3->sign_tsig( $opaque );
229
230       The opaque intermediate object references returned during multi-packet
231       signing are not intended to be accessed by the end-user application.
232       Any such access is expressly forbidden.
233
234       Note that a TSIG record is added to every packet; this implementation
235       does not support the suppressed signature scheme described in RFC2845.
236
237   verify and verifyerr
238           $packet->verify()           || die $packet->verifyerr;
239           $reply->verify( $query )    || die $reply->verifyerr;
240
241       Verify TSIG signature of packet or reply to the corresponding query.
242
243           $opaque  =  $packet1->verify( $query ) || die $packet1->verifyerr;
244           $opaque  =  $packet2->verify( $opaque );
245           $verifed =  $packet3->verify( $opaque ) || die $packet3->verifyerr;
246
247       The opaque intermediate object references returned during multi-packet
248       verify() will be undefined (Boolean false) if verification fails.
249       Access to the object itself, if it exists, is expressly forbidden.
250       Testing at every stage may be omitted, which results in a BADSIG error
251       on the final packet in the absence of more specific information.
252
253   sign_sig0
254       SIG0 support is provided through the Net::DNS::RR::SIG class.  The
255       requisite cryptographic components are not integrated into Net::DNS but
256       reside in the Net::DNS::SEC distribution available from CPAN.
257
258           $update = Net::DNS::Update->new('example.com');
259           $update->push( update => rr_add('foo.example.com A 10.1.2.3'));
260           $update->sign_sig0('Kexample.com+003+25317.private');
261
262       Execution will be terminated if Net::DNS::SEC is not available.
263
264   verify SIG0
265           $packet->verify( $keyrr )           || die $packet->verifyerr;
266           $packet->verify( [$keyrr, ...] )    || die $packet->verifyerr;
267
268       Verify SIG0 packet signature against one or more specified KEY RRs.
269
270   sigrr
271           $sigrr = $packet->sigrr() || die 'unsigned packet';
272
273       The sigrr method returns the signature RR from a signed packet or
274       undefined if the signature is absent.
275
276   truncate
277       The truncate method takes a maximum length as argument and then tries
278       to truncate the packet and set the TC bit according to the rules of
279       RFC2181 Section 9.
280
281       The smallest length limit that is honoured is 512 octets.
282

COPYRIGHT

284       Copyright (c)1997-2000 Michael Fuhr.
285
286       Portions Copyright (c)2002-2004 Chris Reinhardt.
287
288       Portions Copyright (c)2002-2009 Olaf Kolkman
289
290       Portions Copyright (c)2007-2019 Dick Franks
291
292       All rights reserved.
293

LICENSE

295       Permission to use, copy, modify, and distribute this software and its
296       documentation for any purpose and without fee is hereby granted,
297       provided that the original copyright notices appear in all copies and
298       that both copyright notice and this permission notice appear in
299       supporting documentation, and that the name of the author not be used
300       in advertising or publicity pertaining to distribution of the software
301       without specific prior written permission.
302
303       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
304       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
305       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
306       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
307       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
308       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
309       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
310

NAME

SYNOPSIS

DESCRIPTION

METHODS

COPYRIGHT

LICENSE

SEE ALSO