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

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

NAME

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

SYNOPSIS

9           use Net::DNS;
10           $tsig = create Net::DNS::RR::TSIG( $keyfile );
11
12           $tsig = create Net::DNS::RR::TSIG( $keyfile,
13                                               fudge => 300
14                                               );
15

DESCRIPTION

17       Class for DNS Transaction Signature (TSIG) resource records.
18

METHODS

20       The available methods are those inherited from the base class augmented
21       by the type-specific methods defined in this package.
22
23       Use of undocumented package features or direct access to internal data
24       structures is discouraged and could result in program termination or
25       other unpredictable behaviour.
26
27   algorithm
28           $algorithm = $rr->algorithm;
29           $rr->algorithm( $algorithm );
30
31       A domain name which specifies the name of the algorithm.
32
33   key
34           $rr->key( $key );
35
36       Base64 representation of the key material.
37
38   keybin
39           $rr->keybin( $keybin );
40
41       Binary representation of the key material.
42
43   time_signed
44           $time_signed = $rr->time_signed;
45           $rr->time_signed( $time_signed );
46
47       Signing time as the number of seconds since 1 Jan 1970 00:00:00 UTC.
48       The default signing time is the current time.
49
50   fudge
51           $fudge = $rr->fudge;
52           $rr->fudge( $fudge );
53
54       "fudge" represents the permitted error in the signing time.  The
55       default fudge is 300 seconds.
56
57   mac
58           $rr->mac( $mac );
59
60       Message authentication code (MAC).  The programmer must call the
61       Net::DNS::Packet data() object method before this will return anything
62       meaningful.
63
64   macbin
65           $macbin = $rr->macbin;
66           $rr->macbin( $macbin );
67
68       Binary message authentication code (MAC).
69
70   prior_mac
71           $prior_mac = $rr->prior_mac;
72           $rr->prior_mac( $prior_mac );
73
74       Prior message authentication code (MAC).
75
76   prior_macbin
77           $prior_macbin = $rr->prior_macbin;
78           $rr->prior_macbin( $prior_macbin );
79
80       Binary prior message authentication code.
81
82   request_mac
83           $request_mac = $rr->request_mac;
84           $rr->request_mac( $request_mac );
85
86       Request message authentication code (MAC).
87
88   request_macbin
89           $request_macbin = $rr->request_macbin;
90           $rr->request_macbin( $request_macbin );
91
92       Binary request message authentication code.
93
94   original_id
95           $original_id = $rr->original_id;
96           $rr->original_id( $original_id );
97
98       The message ID from the header of the original packet.
99
100   error
101   vrfyerrstr
102            $rcode = $tsig->error;
103
104       Returns the RCODE covering TSIG processing.  Common values are NOERROR,
105       BADSIG, BADKEY, and BADTIME.  See RFC 2845 for details.
106
107   other
108            $other = $tsig->other;
109
110       This field should be empty unless the error is BADTIME, in which case
111       it will contain the server time as the number of seconds since 1 Jan
112       1970 00:00:00 UTC.
113
114   sig_function
115           sub signing_function {
116               my ( $keybin, $data ) = @_;
117
118               my $hmac = new Digest::HMAC( $keybin, 'Digest::MD5' );
119               $hmac->add( $data );
120               return $hmac->digest;
121           }
122
123           $tsig->sig_function( \&signing_function );
124
125       This sets the signing function to be used for this TSIG record.  The
126       default signing function is HMAC-MD5.
127
128   sig_data
129            $sigdata = $tsig->sig_data($packet);
130
131       Returns the packet packed according to RFC2845 in a form for signing.
132       This is only needed if you want to supply an external signing function,
133       such as is needed for TSIG-GSS.
134
135   create
136           $tsig = create Net::DNS::RR::TSIG( $keyfile );
137
138           $tsig = create Net::DNS::RR::TSIG( $keyfile,
139                                               fudge => 300
140                                               );
141
142       Returns a TSIG RR constructed using the parameters in the specified key
143       file, which is assumed to have been generated by dnssec-keygen.
144
145           $tsig = create Net::DNS::RR::TSIG( $keyname, $key );
146
147       The two argument form is supported for backward compatibility.
148
149   verify
150           $verify = $tsig->verify( $data );
151           $verify = $tsig->verify( $packet );
152
153           $verify = $tsig->verify( $reply,  $query );
154
155           $verify = $tsig->verify( $packet, $prior );
156
157       The boolean verify method will return true if the hash over the packet
158       data conforms to the data in the TSIG itself
159

TSIG Keys

161       TSIG keys are symmetric keys generated using dnssec-keygen:
162
163               $ dnssec-keygen -a HMAC-SHA1 -b 160 -n HOST <keyname>
164
165               The key will be stored as a private and public keyfile pair
166               K<keyname>+161+<keyid>.private and K<keyname>+161+<keyid>.key
167
168           where
169               <keyname> is the DNS name of the key.
170
171               <keyid> is the (generated) numerical identifier used to
172               distinguish this key.
173
174       Other algorithms may be substituted for HMAC-SHA1 in the above example.
175
176       It is recommended that the keyname be globally unique and incorporate
177       the fully qualified domain names of the resolver and nameserver in that
178       order. It should be possible for more than one key to be in use
179       simultaneously between any such pair of hosts.
180
181       Although the formats differ, the private and public keys are identical
182       and both should be stored and handled as secret data.
183

Configuring BIND Nameserver

185       The following lines must be added to the /etc/named.conf file:
186
187           key <keyname> {
188               algorithm HMAC-SHA1;
189               secret "<keydata>";
190           };
191
192       <keyname> is the name of the key chosen when the key was generated.
193
194       <keydata> is the key string extracted from the generated key file.
195

ACKNOWLEDGMENT

197       Most of the code in the Net::DNS::RR::TSIG module was contributed by
198       Chris Turbeville.
199
200       Support for external signing functions was added by Andrew Tridgell.
201
202       TSIG verification, BIND keyfile handling and support for HMAC-SHA1,
203       HMAC-SHA224, HMAC-SHA256, HMAC-SHA384 and HMAC-SHA512 functions was
204       added by Dick Franks.
205

BUGS

207       A 32-bit representation of time is used, contrary to RFC2845 which
208       demands 48 bits.  This design decision will need to be reviewed before
209       the code stops working on 7 February 2106.
210

COPYRIGHT

212       Copyright (c)2000,2001 Michael Fuhr.
213
214       Portions Copyright (c)2002,2003 Chris Reinhardt.
215
216       Portions Copyright (c)2013 Dick Franks.
217
218       All rights reserved.
219
220       Package template (c)2009,2012 O.M.Kolkman and R.W.Franks.
221

LICENSE

223       Permission to use, copy, modify, and distribute this software and its
224       documentation for any purpose and without fee is hereby granted,
225       provided that the above copyright notice appear in all copies and that
226       both that copyright notice and this permission notice appear in
227       supporting documentation, and that the name of the author not be used
228       in advertising or publicity pertaining to distribution of the software
229       without specific prior written permission.
230
231       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
232       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
233       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
234       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
235       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
236       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
237       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
238