.\" 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::RRSIG 3pm"
.TH RR::RRSIG 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::RRSIG \- DNS RRSIG resource record
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\f(CW\*(C`use Net::DNS::RR;\*(C'\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Class for \s-1DNS\s0 Address (\s-1RRSIG\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-1RRSIG\s0 \s-1RR\s0 is an implementation of \s-1RFC\s0 4034. 
See Net::DNS::RR::SIG for an impelementation of \s-1SIG0\s0 (\s-1RFC\s0 2931).
.SH "METHODS"
.IX Header "METHODS"
.SS "create"
.IX Subsection "create"
Create a signature over a \s-1RR\s0 set.
.PP
.Vb 8
\&    my $keypath= 
\&            "/home/olaf/keys/Kbla.foo.+001+60114.private";
\&    my $sigrr= create Net::DNS::RR::RRSIG(\e@datarrset,
\&                                        $keypath);
\&    my $sigrr= create Net::DNS::RR::RRSIG(\e@datarrset,
\&                                        $keypath,
\&                                        %arguments);
\&    $sigrr\->print;
\&
\&
\&
\&    #Alternatively use Net::DNS::SEC::Private 
\&
\&    my $private=Net::DNS::SEC::Private\-new(
\&        "/home/olaf/keys/Kbla.foo.+001+60114.private");
\&    my $sigrr= create Net::DNS::RR::RRSIG(\e@datarrset,
\&                                          $private);
.Ve
.PP
create is an alternative constructor for a \s-1RRSIG\s0 \s-1RR\s0 object.
.PP
The first argument is either reference to an array that contains the
RRset that needs to be signed.
.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 for SIG0s and days
for other signatures (sigex=sigin+sigval).  If sigval is specified
then sigex is ignored. The default for sigval is 5 minutes for SIG0s
and 30 days other types of signatures.
.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,5 and 7) and \s-1DSA\s0 signatures 
  (algorithm 3, and 6) have been implemented.
.SS "typecovered"
.IX Subsection "typecovered"
.Vb 1
\&    print "typecovered =", $rr\->typecovered, "\en"
.Ve
.PP
Returns the qtype covered by the sig.
.SS "algorithm"
.IX Subsection "algorithm"
.Vb 1
\&    print "algorithm =", $rr\->algorithm, "\en"
.Ve
.PP
Returns the algorithm number used for the signature
.SS "labels"
.IX Subsection "labels"
.Vb 1
\&    print "labels =", $rr\->labels, "\en"
.Ve
.PP
Returns the the number of labels of the RRs over wich the 
sig was made.
.SS "orgttl"
.IX Subsection "orgttl"
.Vb 1
\&    print "orgttl =", $rr\->orgttl, "\en"
.Ve
.PP
Returns the RRs the original \s-1TTL\s0 of 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.
.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 3
\&    $sigrr\->verify($data, $keyrr) || croak $sigrr\->vrfyerrstr;
\&    $sigrr\->verify($data, [$keyrr, $keyrr2, $keyrr3]) || 
\&                  croak $sigrr\->vrfyerrstr;
.Ve
.PP
If \f(CW$data\fR contains a reference to an array of \s-1RR\s0 objects then them
method verifies the RRset against the signature contained in the
\&\f(CW$sigrr\fR object itself using the public key in \f(CW$keyrr\fR.  Because of the
KeyID bug in bind (see below) a check on keyid is not performed.
.PP
If \f(CW$data\fR contains a reference to a Net::DNS::Packet 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
The second argument can either be a Net::DNS::RR::KEYRR object or a
reference to an array of such objects. Verification will return
successful as soon as one of the keys in the array leads to positive
validation.
.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.
.PP
\&\- If this code is still around by 2030 you have a few years to check
the proper handling of times...
.PP
\&\- Add wildcard handling
.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, <tjmather@tjmather.com>, 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 
Copyright (c) 2007 \- 2008  NLnet Labs.  Author Olaf M. Kolkman 
<olaf@net\-dns.org>
.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/ <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, Net::DNS::SEC::Private, \s-1RFC\s0 4034