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

Remarks

143       - The code is not optimized for speed whatsoever. It is probably not
144         suitable to be used for signing large zones.
145

TODO

147       - Clean up the code, it still contains some cruft left from the times
148       that
149         the SIG RR was used for signing packets and RR sets.
150
151       - If this code is still around by 2030 you have a few years to check
152         the proper handling of times...
153

ACKNOWLEDGMENTS

155       Andy Vaskys (Network Associates Laboratories) supplied the code for
156       handling RSA with SHA1 (Algorithm 5).
157
158       Chris Reinardt for maintianing Net::DNS.
159
160       T.J. Mather, <tjmather@tjmather.com>, the Crypt::OpenSSL::DSA
161       maintainer, for his quick responses to bug report and feature requests.
162

COPYRIGHT

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