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

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

NAME

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

SYNOPSIS

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

DESCRIPTION

12       IMPORTANT: For any other use than SIG0 signatures the SIG RR has been
13       deprecated (RFC3755). Use the DNSSIG instead.
14
15       All functionality currently remains present although a warning will be
16       printed at first usage of the verify and create methods.
17
18       Class for DNS Address (SIG) resource records. In addition to the regu‐
19       lar methods in the Net::DNS::RR the Class contains a method to sign
20       RRsets using private keys (create). And a class for verifying signa‐
21       tures over RRsets (verify).
22
23       The SIG RR is an implementation of RFC 2931.
24

SIG0 Support

26       When Net::DNS::RR::SIG.pm is available the Net::DNS::Packet module will
27       have the abilityh for sig0 support. See Net::DNS::Packet for details.
28
29           my $keypathrsa="Ktest.example.+001+11567.private";
30           my $update1 = Net::DNS::Update->new("test.example");
31
32           $update1->push("update", Net::DNS::rr_add("foo.test.example 3600 IN A 10.0.0.1"));
33           $update1->sign_sig0($keypathrsa);
34

METHODS

36       create
37
38       create is an alternative constructor for a SIG RR object.
39
40       You are advised to create a packet object and then use the sign_sig0
41       method to create a sig0 signature.
42
43       To create a signature over a packet (SIG0) you can use the following
44       alternative recipe.
45
46           my $keypath=
47                   "/home/olaf/keys/Kbla.foo.+001+60114.private";
48
49           $sig0 = Net::DNS::RR::SIG->create('', $keypath);
50           $packet->push('additional', $sig0) if $sig0;
51           $packet->data;  # When the data method on a packet is called
52                           # the actual sig0 calculation is done.
53
54       The first argument to the create method should be an empty string in
55       order for the SIG0 magic to work.
56
57       The second argument is a string containing the path to a file contain‐
58       ing the the private key as generated with dnssec-keygen, a program that
59       commes with the bind distribution.
60
61       The third argument is an anonymous hash containing the following possi‐
62       ble arguments:
63
64           ( ttl => 3600,                        # TTL
65             sigin =>   20010501010101,          # signature inception
66             sigex =>   20010501010101,          # signature expiration
67             sigval => 1.5                       # signature validity
68             )
69
70       The default for the ttl is 3600 seconds. sigin and sigex need to be
71       specified in the following format 'yyyymmddhhmmss'. The default for
72       sigin is the time of signing.
73
74       sigval is the validity of the signature in minutes. If sigval is speci‐
75       fied then sigex is ignored. The default for sigval is 5 minutes.
76
77       Note that for SIG0 signatures the default sigin is calculated at the
78       moment the object is created, not at the moment that the packet is put
79       on the wire.
80
81       Notes:
82
83       - Do not change the name of the file generated by dnssec-keygen, the
84         create method uses the filename as generated by dnssec-keygen to
85       determine
86         the keyowner, algorithm and the keyid (keytag).
87
88       - Only RSA signatures (algorithm 1 and 5) and DSA signatures
89         (algorithm 3) have been implemented.
90
91       typecovered
92
93           print "typecovered =", $rr->typecovered, "\n"
94
95       Returns the type covered by the sig (should be TYPE000 with common SIG0
96       usage)
97
98       algorithm
99
100           print "algorithm =", $rr->algorithm, "\n"
101
102       Returns the algorithm number used for the signature
103
104       sigexpiration
105
106           print "sigexpiration =", $rr->sigexpiration, "\n"
107
108       Returns the expiration date of the signature
109
110       siginception
111
112           print "siginception =", $rr->siginception, "\n"
113
114       Returns the date the signature was incepted.
115
116       keytag
117
118           print "keytag =", $rr->keytag, "\n"
119
120       Returns the the keytag (key id) of the key the sig was made with.  Read
121       "KeyID Bug in bind." below.
122
123       signame
124
125           print "signame =", $rr->signame, "\n"
126
127       Returns the name of the public KEY RRs  this sig was made with.  (Note:
128       the name does not contain a trailing dot.)
129
130       sig
131
132           print "sig =", $rr->sig, "\n"
133
134       Returns the base64 representation of the signature.
135
136       verify and vrfyerrstr
137
138           my $sigrr=$update1->pop("additional");
139           $sigrr->verify($packet, $keyrr) ⎪⎪ croak $sigrr->vrfyerrstr;
140
141       If the first argument is a Net::DNS::Packet object and if $sig->type
142       equals zero a a sig0 verification is performed. Note that the signature
143       needs to be 'popped' from the packet before verifying.
144
145       Returns 0 on error and sets $sig->vrfyerrstr
146
147       Example
148
149          my $sigrr=$packet->pop("additional");
150          print $sigrr->vrfyerrstr unless $sigrr1->verify($update1, $keyrr1);
151

Remarks

153       - The code is not optimized for speed whatsoever. It is probably not
154         suitable to be used for signing large zones.
155

TODO

157       - Clean up the code, it still contains some cruft left from the times
158       that
159         the SIG RR was used for signing packets and RR sets.
160
161       - If this code is still around by 2030 you have a few years to check
162         the proper handling of times...
163

ACKNOWLEDGMENTS

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

COPYRIGHT

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