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 = Net::DNS::RR::TSIG->create( $keyfile );
11
12           $tsig = Net::DNS::RR::TSIG->create( $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 RFC8945 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 = Digest::HMAC->new( $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 RFC8945 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 = Net::DNS::RR::TSIG->create( $keyfile );
137
138           $tsig = Net::DNS::RR::TSIG->create( $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 tsig-keygen.
144
145   verify
146           $verify = $tsig->verify( $data );
147           $verify = $tsig->verify( $packet );
148
149           $verify = $tsig->verify( $reply,  $query );
150
151           $verify = $tsig->verify( $packet, $prior );
152
153       The boolean verify method will return true if the hash over the packet
154       data conforms to the data in the TSIG itself
155

TSIG Keys

157       The TSIG authentication mechanism employs shared secret keys to
158       establish a trust relationship between two entities.
159
160       It should be noted that it is possible for more than one key to be in
161       use simultaneously between any such pair of entities.
162
163       TSIG keys are generated using the tsig-keygen utility distributed with
164       ISC BIND:
165
166           tsig-keygen -a HMAC-SHA256 host1-host2.example.
167
168       Other algorithms may be substituted for HMAC-SHA256 in the above
169       example.
170
171       These keys must be protected in a manner similar to private keys, lest
172       a third party masquerade as one of the intended parties by forging the
173       message authentication code (MAC).
174

Configuring BIND Nameserver

176       The generated key must be added to the /etc/named.conf configuration or
177       a separate file introduced by the $INCLUDE directive:
178
179           key "host1-host2.example. {
180               algorithm hmac-sha256;
181               secret "Secret+known+only+by+participating+entities=";
182           };
183

ACKNOWLEDGMENT

185       Most of the code in the Net::DNS::RR::TSIG module was contributed by
186       Chris Turbeville.
187
188       Support for external signing functions was added by Andrew Tridgell.
189
190       TSIG verification, BIND keyfile handling and support for HMAC-SHA1,
191       HMAC-SHA224, HMAC-SHA256, HMAC-SHA384 and HMAC-SHA512 functions was
192       added by Dick Franks.
193

BUGS

195       A 32-bit representation of time is used, contrary to RFC8945 which
196       demands 48 bits.  This design decision will need to be reviewed before
197       the code stops working on 7 February 2106.
198

COPYRIGHT

200       Copyright (c)2000,2001 Michael Fuhr.
201
202       Portions Copyright (c)2002,2003 Chris Reinhardt.
203
204       Portions Copyright (c)2013,2020 Dick Franks.
205
206       All rights reserved.
207
208       Package template (c)2009,2012 O.M.Kolkman and R.W.Franks.
209

LICENSE

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