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

1Net::DNS::RR::RRSIG(3)User Contributed Perl DocumentationNet::DNS::RR::RRSIG(3)
2
3
4

NAME

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

SYNOPSIS

9           use Net::DNS;
10           $rr = new Net::DNS::RR('name RRSIG typecovered algorithm labels
11                                       orgttl sigexpiration siginception
12                                       keytag signame signature');
13
14           use Net::DNS::SEC;
15           $sigrr = create Net::DNS::RR::RRSIG( \@rrset, $keypath,
16                                               sigex => 20191231010101
17                                               sigin => 20191201010101
18                                               );
19
20           $sigrr->verify( \@rrset, $keyrr ) || die $sigrr->vrfyerrstr;
21

DESCRIPTION

23       Class for DNS digital signature (RRSIG) resource records.
24
25       In addition to the regular methods inherited from Net::DNS::RR the
26       class contains a method to sign RRsets using private keys (create) and
27       a method for verifying signatures over RRsets (verify).
28
29       The RRSIG RR is an implementation of RFC4034.  See Net::DNS::RR::SIG
30       for an implementation of SIG0 (RFC2931).
31

METHODS

33       The available methods are those inherited from the base class augmented
34       by the type-specific methods defined in this package.
35
36       Use of undocumented package features or direct access to internal data
37       structures is discouraged and could result in program termination or
38       other unpredictable behaviour.
39
40   typecovered
41           $typecovered = $rr->typecovered;
42
43       The typecovered field identifies the type of the RRset that is covered
44       by this RRSIG record.
45
46   algorithm
47           $algorithm = $rr->algorithm;
48
49       The algorithm number field identifies the cryptographic algorithm used
50       to create the signature.
51
52       algorithm() may also be invoked as a class method or simple function to
53       perform mnemonic and numeric code translation.
54
55   labels
56           $labels = $rr->labels;
57           $rr->labels( $labels );
58
59       The labels field specifies the number of labels in the original RRSIG
60       RR owner name.
61
62   orgttl
63           $orgttl = $rr->orgttl;
64           $rr->orgttl( $orgttl );
65
66       The original TTL field specifies the TTL of the covered RRset as it
67       appears in the authoritative zone.
68
69   sigexpiration and siginception times
70   sigex sigin sigval
71           $expiration = $rr->sigexpiration;
72           $expiration = $rr->sigexpiration( $value );
73
74           $inception = $rr->siginception;
75           $inception = $rr->siginception( $value );
76
77       The signature expiration and inception fields specify a validity time
78       interval for the signature.
79
80       The value may be specified by a string with format 'yyyymmddhhmmss' or
81       a Perl time() value.
82
83       Return values are dual-valued, providing either a string value or
84       numerical Perl time() value.
85
86   keytag
87           $keytag = $rr->keytag;
88           $rr->keytag( $keytag );
89
90       The keytag field contains the key tag value of the DNSKEY RR that
91       validates this signature.
92
93   signame
94           $signame = $rr->signame;
95           $rr->signame( $signame );
96
97       The signer name field value identifies the owner name of the DNSKEY RR
98       that a validator is supposed to use to validate this signature.
99
100   signature
101   sig
102           $sig = $rr->sig;
103           $rr->sig( $sig );
104
105       The Signature field contains the cryptographic signature that covers
106       the RRSIG RDATA (excluding the Signature field) and the RRset specified
107       by the RRSIG owner name, RRSIG class, and RRSIG type covered fields.
108
109   sigbin
110           $sigbin = $rr->sigbin;
111           $rr->sigbin( $sigbin );
112
113       Binary representation of the cryptographic signature.
114
115   create
116       Create a signature over a RR set.
117
118           use Net::DNS::SEC;
119
120           $keypath = '/home/olaf/keys/Kbla.foo.+001+60114.private';
121
122           $sigrr = create Net::DNS::RR::RRSIG( \@rrsetref, $keypath );
123
124           $sigrr = create Net::DNS::RR::RRSIG( \@rrsetref, $keypath,
125                                               sigex => 20191231010101
126                                               sigin => 20191201010101
127                                               );
128           $sigrr->print;
129
130
131           # Alternatively use Net::DNS::SEC::Private
132
133           $private = Net::DNS::SEC::Private->new($keypath);
134
135           $sigrr= create Net::DNS::RR::RRSIG( \@rrsetref, $private );
136
137       create() is an alternative constructor for a RRSIG RR object.
138
139       This method returns an RRSIG with the signature over the subject rrset
140       (an array of RRs) made with the private key stored in the key file.
141
142       The first argument is a reference to an array that contains the RRset
143       that needs to be signed.
144
145       The second argument is a string which specifies the path to a file
146       containing the private key as generated by dnssec-keygen.
147
148       The optional remaining arguments consist of ( name => value ) pairs as
149       follows:
150
151               sigex  => 20191231010101,       # signature expiration
152               sigin  => 20191201010101,       # signature inception
153               sigval => 30,                   # validity window (days)
154               ttl    => 3600                  # TTL
155
156       The sigin and sigex values may be specified as Perl time values or as a
157       string with the format 'yyyymmddhhmmss'. The default for sigin is the
158       time of signing.
159
160       The sigval argument specifies the signature validity window in days (
161       sigex = sigin + sigval ).
162
163       By default the signature is valid for 30 days.
164
165       By default the TTL matches the RRset that is presented for signing.
166
167   verify
168           $verify = $sigrr->verify( $rrsetref, $keyrr );
169           $verify = $sigrr->verify( $rrsetref, [$keyrr, $keyrr2, $keyrr3] );
170
171       $rrsetref contains a reference to an array of RR objects and the method
172       verifies the RRset against the signature contained in the $sigrr object
173       itself using the public key in $keyrr.
174
175       The second argument can either be a Net::DNS::RR::KEYRR object or a
176       reference to an array of such objects. Verification will return
177       successful as soon as one of the keys in the array leads to positive
178       validation.
179
180       Returns 0 on error and sets $sig->vrfyerrstr
181
182   vrfyerrstr
183           $verify = $sigrr->verify( $rrsetref, $keyrr );
184           print $sigrr->vrfyerrstr unless $verify;
185
186           $sigrr->verify( $rrsetref, $keyrr ) || die $sigrr->vrfyerrstr;
187

KEY GENERATION

189       Private key files and corresponding public DNSKEY records are most
190       conveniently generated using dnssec-keygen, a program that comes with
191       the ISC BIND distribution.
192
193           dnssec-keygen -a 10 -b 2048 -f ksk  rsa.example.
194           dnssec-keygen -a 10 -b 1024         rsa.example.
195
196           dnssec-keygen -a 14 -f ksk  ecdsa.example.
197           dnssec-keygen -a 14         ecdsa.example.
198
199       Do not change the name of the private key file.  The create method uses
200       the filename as generated by dnssec-keygen to determine the keyowner,
201       algorithm, and the keyid (keytag).
202

REMARKS

204       The code is not optimised for speed.  It is probably not suitable to be
205       used for signing large zones.
206
207       If this code is still around in 2100 (not a leap year) you will need to
208       check for proper handling of times after 28th February.
209

ACKNOWLEDGMENTS

211       Although their original code may have disappeared following redesign of
212       Net::DNS, Net::DNS::SEC and the OpenSSL API, the following individual
213       contributors deserve to be recognised for their significant influence
214       on the development of the RRSIG package.
215
216       Andy Vaskys (Network Associates Laboratories) supplied code for RSA.
217
218       T.J. Mather provided support for the DSA algorithm.
219
220       Dick Franks added support for elliptic curve and Edwards curve
221       algorithms.
222
223       Mike McCauley created the Crypt::OpenSSL::ECDSA perl extension module
224       specifically for this development.
225

COPYRIGHT

227       Copyright (c)2001-2005 RIPE NCC,   Olaf M. Kolkman
228
229       Copyright (c)2007-2008 NLnet Labs, Olaf M. Kolkman
230
231       Portions Copyright (c)2014 Dick Franks
232
233       All rights reserved.
234
235       Package template (c)2009,2012 O.M.Kolkman and R.W.Franks.
236

LICENSE

238       Permission to use, copy, modify, and distribute this software and its
239       documentation for any purpose and without fee is hereby granted,
240       provided that the above copyright notice appear in all copies and that
241       both that copyright notice and this permission notice appear in
242       supporting documentation, and that the name of the author not be used
243       in advertising or publicity pertaining to distribution of the software
244       without specific prior written permission.
245
246       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
247       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
248       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
249       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
250       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
251       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
252       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
253