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

Remarks

160       - The code is not optimized for speed whatsoever. It is probably not
161       suitable to be used for signing large zones.
162

TODO

164       - Clean up the code.
165
166       - If this code is still around by 2030 you have a few years to check
167       the proper handling of times...
168
169       - Add wildcard handling
170

ACKNOWLEDGMENTS

172       Andy Vaskys (Network Associates Laboratories) supplied the code for
173       handling RSA with SHA1 (Algorithm 5).
174
175       Chris Reinardt for maintianing Net::DNS.
176
177       T.J. Mather, <tjmather@tjmather.com>, the Crypt::OpenSSL::DSA main‐
178       tainer, for his quick responses to bug report and feature requests.
179

COPYRIGHT

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