1keyrec(3) User Contributed Perl Documentation keyrec(3)
2
6 Net::DNS::SEC::Tools::keyrec - DNSSEC-Tools keyrec file operations
7
9 use Net::DNS::SEC::Tools::keyrec;
10 keyrec_creat("localzone.keyrec");
12 keyrec_open("localzone.keyrec");
13 keyrec_read("localzone.keyrec");
14 @krnames = keyrec_names();
16 $krec = keyrec_fullrec("example.com");
18 %keyhash = %$krec;
19 $zname = $keyhash{"algorithm"};
20 $val = keyrec_recval("example.com","zonefile");
22 $exists = keyrec_exists("example.com");
24 keyrec_add("zone","example.com",\%zone_krfields);
26 keyrec_add("key","Kexample.com.+005+12345",\%keydata);
27 keyrec_del("example.com");
29 keyrec_del("Kexample.com.+005+12345");
30 keyrec_setval("zone","example.com","zonefile","db.example.com");
32 $setname = keyrec_signset_newname("example.com");
34 keyrec_signset_new("zone","example-keys");
36 keyrec_signset_addkey("example-keys","Kexample.com+005+12345",
38 "Kexample.com+005+54321");
39 keyrec_signset_addkey("example-keys",@keylist);
40 keyrec_signset_delkey("example-keys","Kexample.com+005+12345");
42 $flag = keyrec_signset_haskey("example-keys","Kexample.com+005+12345");
44 keyrec_signset_clear("example-keys","Kexample.com+005+12345");
46 @signset = keyrec_signsets();
48 keyrec_settime("zone","example.com");
50 keyrec_settime("set","signing-set-42");
51 keyrec_settime("key","Kexample.com.+005+76543");
52 @keyfields = keyrec_keyfields();
54 @zonefields = keyrec_zonefields();
55 keyrec_write();
57 keyrec_saveas("filecopy.krf);
58 keyrec_close();
59 keyrec_discard();
60 $default_krf = keyrec_defkrf();
62
64 The Net::DNS::SEC::Tools::keyrec module manipulates the contents of a
65 DNSSEC-Tools keyrec file. keyrec files contain data about zones signed
66 by and keys generated by the DNSSEC-Tools programs. Module interfaces
67 exist for looking up keyrec records, creating new records, and modify‐
68 ing existing records.
69 A keyrec file is organized in sets of keyrec records. Each keyrec must
71 be either of key type or zone type. Key keyrecs describe how encryp‐
72 tion keys were generated, zone keyrecs describe how zones were signed.
73 A keyrec consists of a set of keyword/value entries. The following is
74 an example of a key keyrec:
75 key "Kexample.com.+005+30485"
77 zonename "example.com"
78 keyrec_type "kskcur"
79 algorithm "rsasha1"
80 random "/dev/urandom"
81 ksklength "512"
82 ksklife "15768000"
83 keyrec_gensecs "1101183727"
84 keyrec_gendate "Tue Nov 23 04:22:07 2004"
85 The first step in using this module must be to create a new keyrec file
87 or open and read an existing one. The keyrec_creat() interface creates
88 a keyrec file if it does not exist and opens it. The keyrec_open()
89 interface opens an existing keyrec file. The keyrec_read() interface
90 reads the file and parses it into an internal format. The file's
91 records are copied into a hash table (for easy reference by the
92 Net::DNS::SEC::Tools::keyrec routines) and in an array (for preserving
93 formatting and comments.)
94 After the file has been read, the contents are referenced using
96 keyrec_fullrec() and keyrec_recval(). The keyrec contents are modified
97 using keyrec_add(), and keyrec_setval(). keyrec_settime() will update
98 a keyrec's timestamp to the current time. keyrecs may be deleted with
99 the keyrec_del() interface.
100 If the keyrec file has been modified, it must be explicitly written or
102 the changes are not saved. keyrec_write() saves the new contents to
103 disk. keyrec_saveas() saves the in-memory keyrec contents to the spec‐
104 ified file name, without affecting the original file.
105 keyrec_close() saves the file and close the Perl file handle to the
107 keyrec file. If a keyrec file is no longer wanted to be open, yet the
108 contents should not be saved, keyrec_discard() gets rid of the data,
109 and closes the file handle without saving any modified data.
110
112 The interfaces to the Net::DNS::SEC::Tools::keyrec module are given
113 below.
114 keyrec_add(keyrec_type,keyrec_name,fields)
116 This routine adds a new keyrec to the keyrec file and the internal
117 representation of the file contents. The keyrec is added to both
118 the %keyrecs hash table and the @keyreclines array.
119 keyrec_type specifies the type of the keyrec -- "key" or "zone".
121 keyrec_name is the name of the keyrec. fields is a reference to a
122 hash table that contains the name/value keyrec fields. The keys of
123 the hash table are always converted to lowercase, but the entry
124 values are left as given.
125 The ksklength entry is only added if the value of the keyrec_type
127 field is "kskcur".
128 The zsklength entry is only added if the value of the keyrec_type
130 field is "zsk", "zskcur", "zskpub", or "zsknew".
131 Timestamp fields are added at the end of the keyrec. For key
133 keyrecs, the keyrec_gensecs and keyrec_gendate timestamp fields are
134 added. For zone keyrecs, the keyrec_signsecs and keyrec_signdate
135 timestamp fields are added.
136 If a specified field isn't defined for the keyrec type, the entry
138 isn't added. This prevents zone keyrec data from getting mingled
139 with key keyrec data.
140 A blank line is added after the final line of the new keyrec.
142 After adding all new keyrec entries, the keyrec file is written but
143 is not closed.
144 Return values are:
146 0 success
148 -1 invalid I<krtype>
149 keyrec_close()
151 This interface saves the internal version of the keyrec file
152 (opened with keyrec_creat(), keyrec_open() or keyrec_read()) and
153 closes the file handle.
154 keyrec_creat(keyrec_file)
156 This interface creates a keyrec file if it does not exist, and
157 truncates the file if it already exists. It leaves the file in the
158 open state.
159 keyrec_creat() returns 1 if the file was created successfully. It
161 returns 0 if there was an error in creating the file.
162 keyrec_defkrf()
164 This routine returns the default keyrec filename from the DNSSEC-
165 Tools configuration file.
166 keyrec_del(keyrec_name)
168 This routine deletes a keyrec from the keyrec file and the internal
169 representation of the file contents. The keyrec is deleted from
170 both the %keyrecs hash table and the @keyreclines array.
171 Only the keyrec itself is deleted from the file. Any associated
173 comments and blank lines surrounding it are left intact.
174 Return values are:
176 0 successful I<keyrec> deletion
178 -1 invalid I<krtype> (empty string or unknown name)
179 keyrec_discard()
181 This routine removes a keyrec file from use by a program. The
182 internally stored data are deleted and the keyrec file handle is
183 closed. However, modified data are not saved prior to closing the
184 file handle. Thus, modified and new data will be lost.
185 keyrec_exists(keyrec_name)
187 keyrec_exists() returns a boolean indicating if a keyrec exists
188 that has the specified keyrec_name.
189 keyrec_fullrec(keyrec_name)
191 keyrec_fullrec() returns a reference to the keyrec specified in
192 keyrec_name.
193 keyrec_keyfields()
195 This routine returns a list of the recognized fields for a key
196 keyrec.
197 keyrec_names()
199 This routine returns a list of the keyrec names from the file.
200 keyrec_open(keyrec_file)
202 This interface opens an existing keyrec file. It first attempts to
203 open the keyrec file for reading and writing. If this fails, then
204 it attempts to open it read-only.
205 keyrec_open() returns 1 if the file was opened successfully. It
207 returns 0 if the file does not exists or if there was an error in
208 opening the file.
209 keyrec_read(keyrec_file)
211 This interface reads the specified keyrec file and parses it into a
212 keyrec hash table and a file contents array. keyrec_read() must be
213 called prior to any of the other Net::DNS::SEC::Tools::keyrec
214 calls. If another keyrec is already open, then it is saved and
215 closed prior to opening the new keyrec.
216 Upon success, keyrec_read() returns the number of keyrecs read from
218 the file.
219 Failure return values:
221 -1 specified I<keyrec> file doesn't exit
223 -2 unable to open I<keyrec> file
224 -3 duplicate I<keyrec> names in file
225 keyrec_recval(keyrec_name,keyrec_field)
227 This routine returns the value of a specified field in a given
228 keyrec. keyrec_name is the name of the particular keyrec to con‐
229 sult. keyrec_field is the field name within that keyrec.
230 For example, the current keyrec file contains the following keyrec:
232 zone "example.com"
234 zonefile "db.example.com"
235 The call:
237 keyrec_recval("example.com","zonefile")
239 will return the value "db.example.com".
241 keyrec_saveas(keyrec_file_copy)
243 This interface saves the internal version of the keyrec file
244 (opened with keyrec_creat(), keyrec_open() or keyrec_read()) to the
245 file named in the keyrec_file_copy parameter. The new file's file
246 handle is closed, but the original file and the file handle to the
247 original file are not affected.
248 keyrec_setval(keyrec_type,keyrec_name,field,value)
250 Set the value of a name/field pair in a specified keyrec. The file
251 is not written after updating the value. The value is saved in
252 both %keyrecs and in @keyreclines, and the file-modified flag is
253 set.
254 keyrec_type specifies the type of the keyrec. This is only used if
256 a new keyrec is being created by this call. keyrec_name is the
257 name of the keyrec that will be modified. field is the keyrec
258 field which will be modified. value is the new value for the
259 field.
260 Return values are:
262 0 if the creation succeeded
264 -1 invalid type was given
265 keyrec_settime(keyrec_type,keyrec_name)
267 Set the timestamp of a specified keyrec. The file is not written
268 after updating the value. The value is saved in both %keyrecs and
269 in @keyreclines, and the file-modified flag is set. The keyrec's
270 keyrec_signdate and keyrec_signsecs fields are modified.
271 keyrec_write()
273 This interface saves the internal version of the keyrec file
274 (opened with keyrec_creat(), keyrec_open() or keyrec_read()). It
275 does not close the file handle. As an efficiency measure, an
276 internal modification flag is checked prior to writing the file.
277 If the program has not modified the contents of the keyrec file, it
278 is not rewritten.
279 keyrec_zonefields()
281 This routine returns a list of the recognized fields for a zone
282 keyrec.
283
285 Signing Sets are collections of encryption keys, defined by inclusion
286 in a particular "set" keyrec. The names of the keys are in the
287 keyrec's keys record, which contains the names of the key keyrecs. Due
288 to the way key names are handled, the names in a Signing Set must not
289 contain spaces.
290 The Signing-Set-specific interfaces are given below.
292 keyrec_signset_newname(zone_name)
294 keyrec_signset_newname() creates a name for a new Signing Set. The
295 name will be generated by referencing the lastset field in the
296 keyrec for zone zone_name, if the keyrec has such a field. The set
297 index number (described below) will be incremented and the lastset
298 with the new index number will be returned as the new Signing Set
299 name. If the zone keyrec does not have a lastset field, then the
300 default set name of signing-set-0 will be used.
301 The set index number is the first number found in the lastset
303 field. It doesn't matter where in the field it is found, the first
304 number will be considered to be the Signing Set index. The exam‐
305 ples below show how this is determined:
306 lastset field index
308 ------------- -----
309 signing-set-0 0
310 signing-0-set 0
311 1-signing-0-set 1
312 signing-88-set-1 88
313 signingset4321 4321
314 keyrec_signset_new(signing_set_name)
316 keyrec_signset_new() creates the Signing Set named by sign‐
317 ing_set_name. It returns 1 if the call is successful; 0 if it is
318 not.
319 keyrec_signset_addkey(signing_set_name,key_list)
321 keyrec_signset_addkey() adds the keys listed in key_list to the
322 Signing Set named by signing_set_name. key_list may either be an
323 array or a set or arguments to the routine. The keyrec is created
324 if it does not already exist. It returns 1 if the call is success‐
325 ful; 0 if it is not.
326 keyrec_signset_delkey(signing_set_name,key_name)
328 keyrec_signset_delkey() deletes the key given in key_name to the
329 Signing Set named by signing_set_name. It returns 1 if the call is
330 successful; 0 if it is not.
331 keyrec_signset_haskey(signing_set_name,key_name)
333 keyrec_signset_haskey() returns a flag indicating if the key speci‐
334 fied in key_name is one of the keys in the Signing Set named by
335 signing_set_name. It returns 1 if the signing set has the key; 0
336 if it does not.
337 keyrec_signset_clear(keyrec_name)
339 keyrec_signset_clear() clears the entire signing set from the
340 keyrec named by keyrec_name. It returns 1 if the call is success‐
341 ful; 0 if it is not.
342 keyrec_signsets()
344 keyrec_signsets() returns the names of the signing sets in the
345 keyrec file. These names are returned in an array.
346
348 The interfaces described in this section are intended for internal use
349 by the keyrec.pm module. However, there are situations where external
350 entities may have need of them. Use with caution, as misuse may result
351 in damaged or lost keyrec files.
352 keyrec_init()
354 This routine initializes the internal keyrec data. Pending changes
355 will be lost. An open keyrec file handle will remain open, though
356 the data are no longer held internally. A new keyrec file must be
357 read in order to use the keyrec.pm interfaces again.
358 keyrec_newkeyrec(kr_name,kr_type)
360 This interface creates a new keyrec. The keyrec_name and
361 keyrec_hash fields in the keyrec are set to the values of the
362 kr_name and kr_type parameters. kr_type must be either "key" or
363 "zone".
364 Return values are:
366 0 if the creation succeeded
368 -1 if an invalid I<keyrec> type was given
369
371 The following interfaces display information about the currently parsed
372 keyrec file. They are intended to be used for debugging and testing,
373 but may be useful at other times.
374 keyrec_dump_hash()
376 This routine prints the keyrec file as it is stored internally in a
377 hash table. The keyrecs are printed in alphabetical order, with
378 the fields alphabetized for each keyrec. New keyrecs and keyrec
379 fields are alphabetized along with current keyrecs and fields.
380 Comments from the keyrec file are not included with the hash table.
381 keyrec_dump_array()
383 This routine prints the keyrec file as it is stored internally in
384 an array. The keyrecs are printed in the order given in the file,
385 with the fields ordered in the same manner. New keyrecs are
386 appended to the end of the array. keyrec fields added to existing
387 keyrecs are added at the beginning of the keyrec entry. Comments
388 and vertical whitespace are preserved as given in the keyrec file.
389
391 Copyright 2005-2007 SPARTA, Inc. All rights reserved. See the COPYING
392 file included with the DNSSEC-Tools package for details.
393
395 Wayne Morrison, tewok@users.sourceforge.net
396
398 Net::DNS::SEC::Tools::conf(5), Net::DNS::SEC::Tools::keyrec(5)
399perl v5.8.8 2008-02-15 keyrec(3)