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

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

NAME

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

SYNOPSIS

9           use Net::DNS;
10           $rr = Net::DNS::RR->new('name SIG typecovered algorithm labels
11                                       orgttl sigexpiration siginception
12                                       keytag signame signature');
13
14           use Net::DNS::SEC;
15           $sigrr = Net::DNS::RR::SIG->create( $string, $keypath,
16                                               sigval => 10    # minutes
17                                               );
18
19           $sigrr->verify( $string, $keyrr ) || die $sigrr->vrfyerrstr;
20           $sigrr->verify( $packet, $keyrr ) || die $sigrr->vrfyerrstr;
21

DESCRIPTION

23       Class for DNS digital signature (SIG) resource records.
24
25       In addition to the regular methods inherited from Net::DNS::RR the
26       class contains a method to sign packets and scalar data strings using
27       private keys (create) and a method for verifying signatures.
28
29       The SIG RR is an implementation of RFC2931.  See Net::DNS::RR::RRSIG
30       for an implementation of RFC4034.
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   algorithm
41           $algorithm = $rr->algorithm;
42
43       The algorithm number field identifies the cryptographic algorithm used
44       to create the signature.
45
46       algorithm() may also be invoked as a class method or simple function to
47       perform mnemonic and numeric code translation.
48
49   sigexpiration and siginception times
50   sigex sigin sigval
51           $expiration = $rr->sigexpiration;
52           $expiration = $rr->sigexpiration( $value );
53
54           $inception = $rr->siginception;
55           $inception = $rr->siginception( $value );
56
57       The signature expiration and inception fields specify a validity time
58       interval for the signature.
59
60       The value may be specified by a string with format 'yyyymmddhhmmss' or
61       a Perl time() value.
62
63       Return values are dual-valued, providing either a string value or
64       numerical Perl time() value.
65
66   keytag
67           $keytag = $rr->keytag;
68           $rr->keytag( $keytag );
69
70       The keytag field contains the key tag value of the KEY RR that
71       validates this signature.
72
73   signame
74           $signame = $rr->signame;
75           $rr->signame( $signame );
76
77       The signer name field value identifies the owner name of the KEY RR
78       that a validator is supposed to use to validate this signature.
79
80   signature
81   sig
82           $sig = $rr->sig;
83           $rr->sig( $sig );
84
85       The Signature field contains the cryptographic signature that covers
86       the SIG RDATA (excluding the Signature field) and the subject data.
87
88   sigbin
89           $sigbin = $rr->sigbin;
90           $rr->sigbin( $sigbin );
91
92       Binary representation of the cryptographic signature.
93
94   create
95       Create a signature over scalar data.
96
97           use Net::DNS::SEC;
98
99           $keypath = '/home/olaf/keys/Kbla.foo.+001+60114.private';
100
101           $sigrr = Net::DNS::RR::SIG->create( $data, $keypath );
102
103           $sigrr = Net::DNS::RR::SIG->create( $data, $keypath,
104                                               sigval => 10
105                                               );
106           $sigrr->print;
107
108
109           # Alternatively use Net::DNS::SEC::Private
110
111           $private = Net::DNS::SEC::Private->new($keypath);
112
113           $sigrr= Net::DNS::RR::SIG->create( $data, $private );
114
115       create() is an alternative constructor for a SIG RR object.
116
117       This method returns a SIG with the signature over the data made with
118       the private key stored in the key file.
119
120       The first argument is a scalar that contains the data to be signed.
121
122       The second argument is a string which specifies the path to a file
123       containing the private key as generated using dnssec-keygen, a program
124       that comes with the ISC BIND distribution.
125
126       The optional remaining arguments consist of ( name => value ) pairs as
127       follows:
128
129               sigin  => 20211201010101,       # signature inception
130               sigex  => 20211201011101,       # signature expiration
131               sigval => 10,                   # validity window (minutes)
132
133       The sigin and sigex values may be specified as Perl time values or as a
134       string with the format 'yyyymmddhhmmss'. The default for sigin is the
135       time of signing.
136
137       The sigval argument specifies the signature validity window in minutes
138       ( sigex = sigin + sigval ).
139
140       By default the signature is valid for 10 minutes.
141
142       •   Do not change the name of the private key file.  The create method
143           uses the filename as generated by dnssec-keygen to determine the
144           keyowner, algorithm, and the keyid (keytag).
145
146   verify
147           $verify = $sigrr->verify( $data, $keyrr );
148           $verify = $sigrr->verify( $data, [$keyrr, $keyrr2, $keyrr3] );
149
150       The verify() method performs SIG0 verification of the specified data
151       against the signature contained in the $sigrr object itself using the
152       public key in $keyrr.
153
154       If a reference to a Net::DNS::Packet is supplied, the method performs a
155       SIG0 verification on the packet data.
156
157       The second argument can either be a Net::DNS::RR::KEYRR object or a
158       reference to an array of such objects. Verification will return
159       successful as soon as one of the keys in the array leads to positive
160       validation.
161
162       Returns false on error and sets $sig->vrfyerrstr
163
164   vrfyerrstr
165           $sig0 = $packet->sigrr || die 'not signed';
166           print $sig0->vrfyerrstr unless $sig0->verify( $packet, $keyrr );
167
168           $sigrr->verify( $packet, $keyrr ) || die $sigrr->vrfyerrstr;
169

REMARKS

171       The code is not optimised for speed.
172
173       If this code is still around in 2100 (not a leap year) you will need to
174       check for proper handling of times after 28th February.
175

ACKNOWLEDGMENTS

177       Although their original code may have disappeared following redesign of
178       Net::DNS, Net::DNS::SEC and the OpenSSL API, the following individual
179       contributors deserve to be recognised for their significant influence
180       on the development of the SIG package.
181
182       Andy Vaskys (Network Associates Laboratories) supplied code for RSA.
183
184       T.J. Mather provided support for the DSA algorithm.
185

COPYRIGHT

187       Copyright (c)2001-2005 RIPE NCC,   Olaf M. Kolkman
188
189       Copyright (c)2007-2008 NLnet Labs, Olaf M. Kolkman
190
191       Portions Copyright (c)2014 Dick Franks
192
193       All rights reserved.
194
195       Package template (c)2009,2012 O.M.Kolkman and R.W.Franks.
196

LICENSE

198       Permission to use, copy, modify, and distribute this software and its
199       documentation for any purpose and without fee is hereby granted,
200       provided that the original copyright notices appear in all copies and
201       that both copyright notice and this permission notice appear in
202       supporting documentation, and that the name of the author not be used
203       in advertising or publicity pertaining to distribution of the software
204       without specific prior written permission.
205
206       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
207       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
208       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
209       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
210       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
211       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
212       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
213