Net::DNS::RR::RRSIG(3pm)

1RR::RRSIG(3)          User Contributed Perl Documentation         RR::RRSIG(3)
2
3
4

NAME

6       Net::DNS::RR::RRSIG - DNS RRSIG resource record
7

SYNOPSIS

9       "use Net::DNS::RR;"
10

DESCRIPTION

12       Class for DNS Address (RRSIG) resource records. In addition to the
13       regular methods in the Net::DNS::RR the Class contains a method to sign
14       RRsets using private keys (create). And a class for verifying
15       signatures over RRsets (verify).
16
17       The RRSIG RR is an implementation of RFC 4034.  See Net::DNS::RR::SIG
18       for an impelementation of SIG0 (RFC 2931).
19

METHODS

21   create
22       Create a signature over a RR set.
23
24           my $keypath=
25                   "/home/olaf/keys/Kbla.foo.+001+60114.private";
26           my $sigrr= create Net::DNS::RR::RRSIG(\@datarrset,
27                                               $keypath);
28           my $sigrr= create Net::DNS::RR::RRSIG(\@datarrset,
29                                               $keypath,
30                                               %arguments);
31           $sigrr->print;
32
33
34
35           #Alternatively use Net::DNS::SEC::Private
36
37           my $private=Net::DNS::SEC::Private-new(
38               "/home/olaf/keys/Kbla.foo.+001+60114.private");
39           my $sigrr= create Net::DNS::RR::RRSIG(\@datarrset,
40                                                 $private);
41
42       create is an alternative constructor for a RRSIG RR object.
43
44       The first argument is either reference to an array that contains the
45       RRset that needs to be signed.
46
47       The second argument is a string containing the path to a file
48       containing the the private key as generated with dnssec-keygen, a
49       program that commes with the bind distribution.
50
51       The third argument is an anonymous hash containing the following
52       possible arguments:
53
54           ( ttl => 3600,                        # TTL
55             sigin =>   20010501010101,          # signature inception
56             sigex =>   20010501010101,          # signature expiration
57             sigval => 1.5                       # signature validity
58             )
59
60       The default for the ttl is 3600 seconds. sigin and sigex need to be
61       specified in the following format 'yyyymmddhhmmss'. The default for
62       sigin is the time of signing.
63
64       sigval is the validity of the signature in minutes for SIG0s and days
65       for other signatures (sigex=sigin+sigval).  If sigval is specified then
66       sigex is ignored. The default for sigval is 5 minutes for SIG0s and 30
67       days other types of signatures.
68
69       Notes:
70
71       - Do not change the name of the file generated by dnssec-keygen, the
72         create method uses the filename as generated by dnssec-keygen to
73         determine the keyowner, algorithm and the keyid (keytag).
74
75       - Only RSA signatures (algorithm 1,5 and 7) and DSA signatures
76         (algorithm 3, and 6) have been implemented.
77
78   typecovered
79           print "typecovered =", $rr->typecovered, "\n"
80
81       Returns the qtype covered by the sig.
82
83   algorithm
84           print "algorithm =", $rr->algorithm, "\n"
85
86       Returns the algorithm number used for the signature
87
88   labels
89           print "labels =", $rr->labels, "\n"
90
91       Returns the the number of labels of the RRs over wich the sig was made.
92
93   orgttl
94           print "orgttl =", $rr->orgttl, "\n"
95
96       Returns the RRs the original TTL of the signature
97
98   sigexpiration
99           print "sigexpiration =", $rr->sigexpiration, "\n"
100
101       Returns the expiration date of the signature
102
103   siginception
104           print "siginception =", $rr->siginception, "\n"
105
106       Returns the date the signature was incepted.
107
108   keytag
109           print "keytag =", $rr->keytag, "\n"
110
111       Returns the the keytag (key id) of the key the sig was made with.  Read
112       "KeyID Bug in bind." below.
113
114   signame
115           print "signame =", $rr->signame, "\n"
116
117       Returns the name of the public KEY RRs  this sig was made with.
118
119   sig
120           print "sig =", $rr->sig, "\n"
121
122       Returns the base64 representation of the signature.
123
124   verify and vrfyerrstr
125           $sigrr->verify($data, $keyrr) || croak $sigrr->vrfyerrstr;
126           $sigrr->verify($data, [$keyrr, $keyrr2, $keyrr3]) ||
127                         croak $sigrr->vrfyerrstr;
128
129       If $data contains a reference to an array of RR objects then them
130       method verifies the RRset against the signature contained in the $sigrr
131       object itself using the public key in $keyrr.  Because of the KeyID bug
132       in bind (see below) a check on keyid is not performed.
133
134       If $data contains a reference to a Net::DNS::Packet and if $sig->type
135       equals zero a a sig0 verification is performed. Note that the signature
136       needs to be 'popped' from the packet before verifying.
137
138       The second argument can either be a Net::DNS::RR::KEYRR object or a
139       reference to an array of such objects. Verification will return
140       successful as soon as one of the keys in the array leads to positive
141       validation.
142
143       Returns 0 on error and sets $sig->vrfyerrstr
144
145   Example
146          my $sigrr=$packet->pop("additional");
147          print $sigrr->vrfyerrstr unless $sigrr1->verify($update1, $keyrr1);
148

Remarks

150       - The code is not optimized for speed whatsoever. It is probably not
151       suitable to be used for signing large zones.
152

TODO

154       - Clean up the code.
155
156       - If this code is still around by 2030 you have a few years to check
157       the proper handling of times...
158
159       - Add wildcard handling
160

ACKNOWLEDGMENTS

162       Andy Vaskys (Network Associates Laboratories) supplied the code for
163       handling RSA with SHA1 (Algorithm 5).
164
165       Chris Reinardt for maintianing Net::DNS.
166
167       T.J. Mather, <tjmather@tjmather.com>, the Crypt::OpenSSL::DSA
168       maintainer, for his quick responses to bug report and feature requests.
169

COPYRIGHT

171       Copyright (c) 2001 - 2005  RIPE NCC.  Author Olaf M. Kolkman Copyright
172       (c) 2007 - 2008  NLnet Labs.  Author Olaf M. Kolkman <olaf@net-dns.org>
173
174       All Rights Reserved
175
176       Permission to use, copy, modify, and distribute this software and its
177       documentation for any purpose and without fee is hereby granted,
178       provided that the above copyright notice appear in all copies and that
179       both that copyright notice and this permission notice appear in
180       supporting documentation, and that the name of the author not be used
181       in advertising or publicity pertaining to distribution of the software
182       without specific, written prior permission.
183
184       THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
185       INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS; IN NO
186       EVENT SHALL AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
187       DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
188       PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
189       ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
190       THIS SOFTWARE.
191
192       Based on, and contains, code by Copyright (c) 1997 Michael Fuhr.
193
194       This code uses Crypt::OpenSSL which uses the openssl library
195