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                       'Khmac-sha512.example.+165+01018.private',
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 historical simplified syntax is still available, but additional
218       options can not be specified.
219
220           $packet->sign_tsig( $key_name, $key );
221
222       The response to an inbound request is signed by presenting the request
223       in place of the key parameter.
224
225           $response = $request->reply;
226           $response->sign_tsig( $request, @options );
227
228       Multi-packet transactions are signed by chaining the sign_tsig() calls
229       together as follows:
230
231           $opaque  =  $packet1->sign_tsig( 'Kexample.+165+13281.private' );
232           $opaque  =  $packet2->sign_tsig( $opaque );
233                       $packet3->sign_tsig( $opaque );
234
235       The opaque intermediate object references returned during multi-packet
236       signing are not intended to be accessed by the end-user application.
237       Any such access is expressly forbidden.
238
239       Note that a TSIG record is added to every packet; this implementation
240       does not support the suppressed signature scheme described in RFC2845.
241
242   verify and verifyerr
243           $packet->verify()           || die $packet->verifyerr;
244           $reply->verify( $query )    || die $reply->verifyerr;
245
246       Verify TSIG signature of packet or reply to the corresponding query.
247
248           $opaque  =  $packet1->verify( $query ) || die $packet1->verifyerr;
249           $opaque  =  $packet2->verify( $opaque );
250           $verifed =  $packet3->verify( $opaque ) || die $packet3->verifyerr;
251
252       The opaque intermediate object references returned during multi-packet
253       verify() will be undefined (Boolean false) if verification fails.
254       Access to the object itself, if it exists, is expressly forbidden.
255       Testing at every stage may be omitted, which results in a BADSIG error
256       on the final packet in the absence of more specific information.
257
258   sign_sig0
259       SIG0 support is provided through the Net::DNS::RR::SIG class.  The
260       requisite cryptographic components are not integrated into Net::DNS but
261       reside in the Net::DNS::SEC distribution available from CPAN.
262
263           $update = Net::DNS::Update->new('example.com');
264           $update->push( update => rr_add('foo.example.com A 10.1.2.3'));
265           $update->sign_sig0('Kexample.com+003+25317.private');
266
267       Execution will be terminated if Net::DNS::SEC is not available.
268
269   verify SIG0
270           $packet->verify( $keyrr )           || die $packet->verifyerr;
271           $packet->verify( [$keyrr, ...] )    || die $packet->verifyerr;
272
273       Verify SIG0 packet signature against one or more specified KEY RRs.
274
275   sigrr
276           $sigrr = $packet->sigrr() || die 'unsigned packet';
277
278       The sigrr method returns the signature RR from a signed packet or
279       undefined if the signature is absent.
280
281   truncate
282       The truncate method takes a maximum length as argument and then tries
283       to truncate the packet and set the TC bit according to the rules of
284       RFC2181 Section 9.
285
286       The smallest length limit that is honoured is 512 octets.
287

COPYRIGHT

289       Copyright (c)1997-2000 Michael Fuhr.
290
291       Portions Copyright (c)2002-2004 Chris Reinhardt.
292
293       Portions Copyright (c)2002-2009 Olaf Kolkman
294
295       Portions Copyright (c)2007-2019 Dick Franks
296
297       All rights reserved.
298

LICENSE

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

NAME

SYNOPSIS

DESCRIPTION

METHODS

COPYRIGHT

LICENSE

SEE ALSO