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

COPYRIGHT

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

LICENSE

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

NAME

SYNOPSIS

DESCRIPTION

METHODS

COPYRIGHT

LICENSE

SEE ALSO