{ "content": [ { "type": "text", "text": "# Net::DNS::Packet (perldoc)\n\n## NAME\n\nNet::DNS::Packet - DNS protocol packet\n\n## SYNOPSIS\n\nuse Net::DNS::Packet;\n$query = Net::DNS::Packet->new( 'example.com', 'MX', 'IN' );\n$reply = $resolver->send( $query );\n\n## DESCRIPTION\n\nA Net::DNS::Packet object represents a DNS protocol packet.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **COPYRIGHT**\n- **LICENSE**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Net::DNS::Packet", "section": "", "mode": "perldoc", "summary": "Net::DNS::Packet - DNS protocol packet", "synopsis": "use Net::DNS::Packet;\n$query = Net::DNS::Packet->new( 'example.com', 'MX', 'IN' );\n$reply = $resolver->send( $query );", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 2, "subsections": [] }, { "name": "METHODS", "lines": 251, "subsections": [] }, { "name": "COPYRIGHT", "lines": 10, "subsections": [] }, { "name": "LICENSE", "lines": 12, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] } ], "sections": { "NAME": { "content": "Net::DNS::Packet - DNS protocol packet\n", "subsections": [] }, "SYNOPSIS": { "content": "use Net::DNS::Packet;\n\n$query = Net::DNS::Packet->new( 'example.com', 'MX', 'IN' );\n\n$reply = $resolver->send( $query );\n", "subsections": [] }, "DESCRIPTION": { "content": "A Net::DNS::Packet object represents a DNS protocol packet.\n", "subsections": [] }, "METHODS": { "content": "new\n$packet = Net::DNS::Packet->new( 'example.com' );\n$packet = Net::DNS::Packet->new( 'example.com', 'MX', 'IN' );\n\n$packet = Net::DNS::Packet->new();\n\nIf passed a domain, type, and class, new() creates a Net::DNS::Packet object which is suitable\nfor making a DNS query for the specified information. The type and class may be omitted; they\ndefault to A and IN.\n\nIf called with an empty argument list, new() creates an empty packet.\n\n$packet = Net::DNS::Packet->decode( \\$data );\n$packet = Net::DNS::Packet->decode( \\$data, 1 ); # debug\n$packet = Net::DNS::Packet->new( \\$data ... );\n\nIf passed a reference to a scalar containing DNS packet data, a new packet object is created by\ndecoding the data. The optional second boolean argument enables debugging output.\n\nReturns undef if unable to create a packet object.\n\nDecoding errors, including data corruption and truncation, are collected in the $@ ($EVALERROR)\nvariable.\n\n( $packet, $length ) = Net::DNS::Packet->decode( \\$data );\n\nIf called in array context, returns a packet object and the number of octets successfully\ndecoded.\n\nNote that the number of RRs in each section of the packet may differ from the corresponding\nheader value if the data has been truncated or corrupted during transmission.\n\ndata\n$data = $packet->data;\n$data = $packet->data( $size );\n\nReturns the packet data in binary format, suitable for sending as a query or update request to a\nnameserver.\n\nTruncation may be specified using a non-zero optional size argument.\n\nheader\n$header = $packet->header;\n\nConstructor method which returns a Net::DNS::Header object which represents the header section\nof the packet.\n\nedns\n$edns = $packet->edns;\n$version = $edns->version;\n$UDPsize = $edns->size;\n\nAuxiliary function which provides access to the EDNS protocol extension OPT RR.\n\nreply\n$reply = $query->reply( $UDPmax );\n\nConstructor method which returns a new reply packet.\n\nThe optional UDPsize argument is the maximum UDP packet size which can be reassembled by the\nlocal network stack, and is advertised in response to an EDNS query.\n\nquestion, zone\n@question = $packet->question;\n\nReturns a list of Net::DNS::Question objects representing the question section of the packet.\n\nIn dynamic update packets, this section is known as zone() and specifies the DNS zone to be\nupdated.\n\nanswer, pre, prerequisite\n@answer = $packet->answer;\n\nReturns a list of Net::DNS::RR objects representing the answer section of the packet.\n\nIn dynamic update packets, this section is known as pre() or prerequisite() and specifies the\nRRs or RRsets which must or must not preexist.\n\nauthority, update\n@authority = $packet->authority;\n\nReturns a list of Net::DNS::RR objects representing the authority section of the packet.\n\nIn dynamic update packets, this section is known as update() and specifies the RRs or RRsets to\nbe added or deleted.\n\nadditional\n@additional = $packet->additional;\n\nReturns a list of Net::DNS::RR objects representing the additional section of the packet.\n\nprint\n$packet->print;\n\nPrints the entire packet to the currently selected output filehandle using the master file\nformat mandated by RFC1035.\n\nstring\nprint $packet->string;\n\nReturns a string representation of the packet.\n\nfrom\nprint \"packet received from \", $packet->from, \"\\n\";\n\nReturns the IP address from which this packet was received. This method will return undef for\nuser-created packets.\n\nsize\nprint \"packet size: \", $packet->size, \" octets\\n\";\n\nReturns the size of the packet in octets as it was received from a nameserver. This method will\nreturn undef for user-created packets (use length($packet->data) instead).\n\npush\n$ancount = $packet->push( prereq => $rr );\n$nscount = $packet->push( update => $rr );\n$arcount = $packet->push( additional => $rr );\n\n$nscount = $packet->push( update => $rr1, $rr2, $rr3 );\n$nscount = $packet->push( update => @rr );\n\nAdds RRs to the specified section of the packet.\n\nReturns the number of resource records in the specified section.\n\nSection names may be abbreviated to the first three characters.\n\nuniquepush\n$ancount = $packet->uniquepush( prereq => $rr );\n$nscount = $packet->uniquepush( update => $rr );\n$arcount = $packet->uniquepush( additional => $rr );\n\n$nscount = $packet->uniquepush( update => $rr1, $rr2, $rr3 );\n$nscount = $packet->uniquepush( update => @rr );\n\nAdds RRs to the specified section of the packet provided that the RRs are not already present in\nthe same section.\n\nReturns the number of resource records in the specified section.\n\nSection names may be abbreviated to the first three characters.\n\npop\nmy $rr = $packet->pop( 'pre' );\nmy $rr = $packet->pop( 'update' );\nmy $rr = $packet->pop( 'additional' );\n\nRemoves a single RR from the specified section of the packet.\n\nsigntsig\n$query = Net::DNS::Packet->new( 'www.example.com', 'A' );\n\n$query->signtsig(\n'Khmac-sha512.example.+165+01018.private',\nfudge => 60\n);\n\n$reply = $res->send( $query );\n\n$reply->verify( $query ) || die $reply->verifyerr;\n\nAttaches a TSIG resource record object, which will be used to sign the packet (see RFC 2845).\n\nThe TSIG record can be customised by optional additional arguments to signtsig() or by calling\nthe appropriate Net::DNS::RR::TSIG methods.\n\nIf you wish to create a TSIG record using a non-standard algorithm, you will have to create it\nyourself. In all cases, the TSIG name must uniquely identify the key shared between the parties,\nand the algorithm name must identify the signing function to be used with the specified key.\n\n$tsig = Net::DNS::RR->new(\nname => 'tsig.example',\ntype => 'TSIG',\nalgorithm => 'custom-algorithm',\nkey => '',\nsigfunction => sub {\nmy ($key, $data) = @;\n...\n}\n);\n\n$query->signtsig( $tsig );\n\nThe historical simplified syntax is still available, but additional options can not be\nspecified.\n\n$packet->signtsig( $keyname, $key );\n\nThe response to an inbound request is signed by presenting the request in place of the key\nparameter.\n\n$response = $request->reply;\n$response->signtsig( $request, @options );\n\nMulti-packet transactions are signed by chaining the signtsig() calls together as follows:\n\n$opaque = $packet1->signtsig( 'Kexample.+165+13281.private' );\n$opaque = $packet2->signtsig( $opaque );\n$packet3->signtsig( $opaque );\n\nThe opaque intermediate object references returned during multi-packet signing are not intended\nto be accessed by the end-user application. Any such access is expressly forbidden.\n\nNote that a TSIG record is added to every packet; this implementation does not support the\nsuppressed signature scheme described in RFC2845.\n\nverify and verifyerr\n$packet->verify() || die $packet->verifyerr;\n$reply->verify( $query ) || die $reply->verifyerr;\n\nVerify TSIG signature of packet or reply to the corresponding query.\n\n$opaque = $packet1->verify( $query ) || die $packet1->verifyerr;\n$opaque = $packet2->verify( $opaque );\n$verifed = $packet3->verify( $opaque ) || die $packet3->verifyerr;\n\nThe opaque intermediate object references returned during multi-packet verify() will be\nundefined (Boolean false) if verification fails. Access to the object itself, if it exists, is\nexpressly forbidden. Testing at every stage may be omitted, which results in a BADSIG error on\nthe final packet in the absence of more specific information.\n\nsignsig0\nSIG0 support is provided through the Net::DNS::RR::SIG class. The requisite cryptographic\ncomponents are not integrated into Net::DNS but reside in the Net::DNS::SEC distribution\navailable from CPAN.\n\n$update = Net::DNS::Update->new('example.com');\n$update->push( update => rradd('foo.example.com A 10.1.2.3'));\n$update->signsig0('Kexample.com+003+25317.private');\n\nExecution will be terminated if Net::DNS::SEC is not available.\n\nverify SIG0\n$packet->verify( $keyrr ) || die $packet->verifyerr;\n$packet->verify( [$keyrr, ...] ) || die $packet->verifyerr;\n\nVerify SIG0 packet signature against one or more specified KEY RRs.\n\nsigrr\n$sigrr = $packet->sigrr() || die 'unsigned packet';\n\nThe sigrr method returns the signature RR from a signed packet or undefined if the signature is\nabsent.\n\ntruncate\nThe truncate method takes a maximum length as argument and then tries to truncate the packet and\nset the TC bit according to the rules of RFC2181 Section 9.\n\nThe smallest length limit that is honoured is 512 octets.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (c)1997-2000 Michael Fuhr.\n\nPortions Copyright (c)2002-2004 Chris Reinhardt.\n\nPortions Copyright (c)2002-2009 Olaf Kolkman\n\nPortions Copyright (c)2007-2019 Dick Franks\n\nAll rights reserved.\n", "subsections": [] }, "LICENSE": { "content": "Permission to use, copy, modify, and distribute this software and its documentation for any\npurpose and without fee is hereby granted, provided that the original copyright notices appear\nin all copies and that both copyright notice and this permission notice appear in supporting\ndocumentation, and that the name of the author not be used in advertising or publicity\npertaining to distribution of the software without specific prior written permission.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING\nBUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,\nDAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n", "subsections": [] }, "SEE ALSO": { "content": "perl, Net::DNS, Net::DNS::Update, Net::DNS::Header, Net::DNS::Question, Net::DNS::RR,\nNet::DNS::RR::TSIG, RFC1035 Section 4.1, RFC2136 Section 2, RFC2845\n", "subsections": [] } } } }