.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "RR::SIG 3pm" .TH RR::SIG 3pm "2010-03-12" "perl v5.12.4" "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::RR::SIG \- DNS SIG resource record .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\f(CW\*(C`use Net::DNS::RR;\*(C'\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1IMPORTANT:\s0 For any other use than \s-1SIG0\s0 signatures the \s-1SIG\s0 \s-1RR\s0 has been deprecated (\s-1RFC3755\s0). Use the \s-1DNSSIG\s0 instead. .PP All functionality currently remains present although a warning will be printed at first usage of the verify and create methods. .PP Class for \s-1DNS\s0 Address (\s-1SIG\s0) resource records. In addition to the regular methods in the Net::DNS::RR the Class contains a method to sign RRsets using private keys (create). And a class for verifying signatures over RRsets (verify). .PP The \s-1SIG\s0 \s-1RR\s0 is an implementation of \s-1RFC\s0 2931. .SH "SIG0 Support" .IX Header "SIG0 Support" When Net::DNS::RR::SIG.pm is available the Net::DNS::Packet module will have the abilityh for sig0 support. See Net::DNS::Packet for details. .PP .Vb 2 \& my $keypathrsa="Ktest.example.+001+11567.private"; \& my $update1 = Net::DNS::Update\->new("test.example"); \& \& $update1\->push("update", Net::DNS::rr_add("foo.test.example 3600 IN A 10.0.0.1")); \& $update1\->sign_sig0($keypathrsa); .Ve .SH "METHODS" .IX Header "METHODS" .SS "create" .IX Subsection "create" create is an alternative constructor for a \s-1SIG\s0 \s-1RR\s0 object. .PP You are advised to create a packet object and then use the sign_sig0 method to create a sig0 signature. .PP To create a signature over a packet (\s-1SIG0\s0) you can use the following alternative recipe. .PP .Vb 2 \& my $keypath= \& "/home/olaf/keys/Kbla.foo.+001+60114.private"; \& \& $sig0 = Net::DNS::RR::SIG\->create(\*(Aq\*(Aq, $keypath); \& $packet\->push(\*(Aqadditional\*(Aq, $sig0) if $sig0; \& $packet\->data; # When the data method on a packet is called \& # the actual sig0 calculation is done. .Ve .PP The first argument to the create method should be an empty string in order for the \s-1SIG0\s0 magic to work. .PP The second argument is a string containing the path to a file containing the the private key as generated with dnssec-keygen, a program that commes with the bind distribution. .PP The third argument is an anonymous hash containing the following possible arguments: .PP .Vb 5 \& ( ttl => 3600, # TTL \& sigin => 20010501010101, # signature inception \& sigex => 20010501010101, # signature expiration \& sigval => 1.5 # signature validity \& ) .Ve .PP The default for the ttl is 3600 seconds. sigin and sigex need to be specified in the following format 'yyyymmddhhmmss'. The default for sigin is the time of signing. .PP sigval is the validity of the signature in minutes. If sigval is specified then sigex is ignored. The default for sigval is 5 minutes. .PP Note that for \s-1SIG0\s0 signatures the default sigin is calculated at the moment the object is created, not at the moment that the packet is put on the wire. .PP Notes: .PP \&\- Do not change the name of the file generated by dnssec-keygen, the create method uses the filename as generated by dnssec-keygen to determine the keyowner, algorithm and the keyid (keytag). .PP \&\- Only \s-1RSA\s0 signatures (algorithm 1 and 5) and \s-1DSA\s0 signatures (algorithm 3) have been implemented. .SS "typecovered" .IX Subsection "typecovered" .Vb 1 \& print "typecovered =", $rr\->typecovered, "\en" .Ve .PP Returns the type covered by the sig (should be \s-1TYPE000\s0 with common \&\s-1SIG0\s0 usage) .SS "algorithm" .IX Subsection "algorithm" .Vb 1 \& print "algorithm =", $rr\->algorithm, "\en" .Ve .PP Returns the algorithm number used for the signature .SS "sigexpiration" .IX Subsection "sigexpiration" .Vb 1 \& print "sigexpiration =", $rr\->sigexpiration, "\en" .Ve .PP Returns the expiration date of the signature .SS "siginception" .IX Subsection "siginception" .Vb 1 \& print "siginception =", $rr\->siginception, "\en" .Ve .PP Returns the date the signature was incepted. .SS "keytag" .IX Subsection "keytag" .Vb 1 \& print "keytag =", $rr\->keytag, "\en" .Ve .PP Returns the the keytag (key id) of the key the sig was made with. Read \*(L"KeyID Bug in bind.\*(R" below. .SS "signame" .IX Subsection "signame" .Vb 1 \& print "signame =", $rr\->signame, "\en" .Ve .PP Returns the name of the public \s-1KEY\s0 RRs this sig was made with. (Note: the name does not contain a trailing dot.) .SS "sig" .IX Subsection "sig" .Vb 1 \& print "sig =", $rr\->sig, "\en" .Ve .PP Returns the base64 representation of the signature. .SS "verify and vrfyerrstr" .IX Subsection "verify and vrfyerrstr" .Vb 2 \& my $sigrr=$update1\->pop("additional"); \& $sigrr\->verify($packet, $keyrr) || croak $sigrr\->vrfyerrstr; .Ve .PP If the first argument is a Net::DNS::Packet object and if \f(CW$sig\fR\->type equals zero a a sig0 verification is performed. Note that the signature needs to be 'popped' from the packet before verifying. .PP Returns 0 on error and sets \f(CW$sig\fR\->vrfyerrstr .SS "Example" .IX Subsection "Example" .Vb 2 \& my $sigrr=$packet\->pop("additional"); \& print $sigrr\->vrfyerrstr unless $sigrr1\->verify($update1, $keyrr1); .Ve .SH "Remarks" .IX Header "Remarks" \&\- The code is not optimized for speed whatsoever. It is probably not suitable to be used for signing large zones. .SH "TODO" .IX Header "TODO" \&\- Clean up the code, it still contains some cruft left from the times that the \s-1SIG\s0 \s-1RR\s0 was used for signing packets and \s-1RR\s0 sets. .PP \&\- If this code is still around by 2030 you have a few years to check the proper handling of times... .SH "ACKNOWLEDGMENTS" .IX Header "ACKNOWLEDGMENTS" Andy Vaskys (Network Associates Laboratories) supplied the code for handling \s-1RSA\s0 with \s-1SHA1\s0 (Algorithm 5). .PP Chris Reinardt for maintianing Net::DNS. .PP T.J. Mather, , the Crypt::OpenSSL::DSA maintainer, for his quick responses to bug report and feature requests. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2001\-2005 \s-1RIPE\s0 \s-1NCC\s0. Author Olaf M. Kolkman .PP All Rights Reserved .PP 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, written prior permission. .PP \&\s-1THE\s0 \s-1AUTHOR\s0 \s-1DISCLAIMS\s0 \s-1ALL\s0 \s-1WARRANTIES\s0 \s-1WITH\s0 \s-1REGARD\s0 \s-1TO\s0 \s-1THIS\s0 \s-1SOFTWARE\s0, \s-1INCLUDING\s0 \&\s-1ALL\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0; \s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1SHALL\s0 \&\s-1AUTHOR\s0 \s-1BE\s0 \s-1LIABLE\s0 \s-1FOR\s0 \s-1ANY\s0 \s-1SPECIAL\s0, \s-1INDIRECT\s0 \s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1OR\s0 \s-1ANY\s0 \&\s-1DAMAGES\s0 \s-1WHATSOEVER\s0 \s-1RESULTING\s0 \s-1FROM\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1USE\s0, \s-1DATA\s0 \s-1OR\s0 \s-1PROFITS\s0, \s-1WHETHER\s0 \s-1IN\s0 \&\s-1AN\s0 \s-1ACTION\s0 \s-1OF\s0 \s-1CONTRACT\s0, \s-1NEGLIGENCE\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1TORTIOUS\s0 \s-1ACTION\s0, \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \&\s-1OR\s0 \s-1IN\s0 \s-1CONNECTION\s0 \s-1WITH\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THIS\s0 \s-1SOFTWARE\s0. .PP Based on, and contains, code by Copyright (c) 1997 Michael Fuhr. .PP This code uses Crypt::OpenSSL which uses the openssl library .SH "SEE ALSO" .IX Header "SEE ALSO" http://www.net\-dns.org/ .PP \&\fIperl\fR\|(1), Net::DNS, Net::DNS::Resolver, Net::DNS::Packet, Net::DNS::Header, Net::DNS::Question, Net::DNS::RR,Crypt::OpenSSL::RSA,Crypt::OpenSSL::DSA, \s-1RFC\s0 2931.