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"); (DEPRECATED)
13 $okfile = keyrec_filestat("localzone.keyrec");
14 keyrec_read("localzone.keyrec");
15 @krnames = keyrec_names();
17 $krec = keyrec_fullrec("example.com");
19 %keyhash = %$krec;
20 $zname = $keyhash{"algorithm"};
21 $val = keyrec_recval("example.com","zonefile");
23 $exists = keyrec_exists("example.com");
25 keyrec_add("zone","example.com",\%zone_krfields);
27 keyrec_add("key","Kexample.com.+005+12345",\%keydata);
28 keyrec_del("example.com");
30 keyrec_setval("zone","example.com","zonefile","db.example.com");
32 keyrec_delval("example.com","kskrev");
34 @kskpaths = keyrec_keypaths("example.com","kskcur");
36 $obsflag = keyrec_revoke_check("Kexample.com.+005+12345");
38 $setname = keyrec_signset_newname("example.com");
40 keyrec_signset_new($zone,"example-set-21","zskcur");
42 keyrec_signset_addkey("example-keys","Kexample.com+005+12345",
44 "Kexample.com+005+54321");
45 keyrec_signset_addkey("example-keys",@keylist);
46 keyrec_signset_delkey("example-keys","Kexample.com+005+12345");
48 $flag = keyrec_signset_haskey("example-keys","Kexample.com+005+12345");
50 keyrec_signset_clear("example-keys","Kexample.com+005+12345");
52 @signset = keyrec_signsets();
54 $sset_prefix = keyrec_signset_prefix("example.com");
56 keyrec_settime("zone","example.com");
58 keyrec_settime("set","signing-set-42");
59 keyrec_settime("key","Kexample.com.+005+76543");
60 @keyfields = keyrec_keyfields();
62 @zonefields = keyrec_zonefields();
63 keyrec_write();
65 keyrec_saveas("filecopy.krf);
66 keyrec_close();
67 keyrec_discard();
68 $current_krf = keyrec_curkrf();
70 $default_krf = keyrec_defkrf();
71
73 The Net::DNS::SEC::Tools::keyrec module manipulates the contents of a
74 DNSSEC-Tools keyrec file. keyrec files contain data about zones signed
75 by and keys generated by the DNSSEC-Tools programs. Module interfaces
76 exist for looking up keyrec records, creating new records, and
77 modifying existing records.
78 A keyrec file is organized in sets of keyrec records. Each keyrec must
80 be either of key type or zone type. Key keyrecs describe how
81 encryption keys were generated, zone keyrecs describe how zones were
82 signed. A keyrec consists of a set of keyword/value entries. The
83 following is an example of a key keyrec:
84 key "Kexample.com.+005+30485"
86 zonename "example.com"
87 keyrec_type "kskcur"
88 algorithm "rsasha1"
89 random "/dev/urandom"
90 ksklength "2048"
91 ksklife "15768000"
92 revperiod "3888000"
93 revtime "1103277532"
94 keyrec_gensecs "1101183727"
95 keyrec_gendate "Tue Nov 23 04:22:07 2004"
96 The first step in using this module must be to create a new keyrec file
98 or open and read an existing one. The keyrec_creat() interface creates
99 a keyrec file if it does not exist. The keyrec_read() interface opens
100 and reads the file, then parses it into an internal format. The file's
101 records are copied into a hash table (for easy and fast reference by
102 the Net::DNS::SEC::Tools::keyrec routines) and in an array (for
103 preserving formatting and comments.) The keyrec_filestat() interface
104 may be used check that the given file may be a keyrec file, though it
105 doesn't check the file's contents.
106 After the file has been read, the contents are referenced using
108 keyrec_fullrec() and keyrec_recval(). The keyrec contents are modified
109 using keyrec_add(), and keyrec_setval(). keyrec_settime() will update
110 a keyrec's timestamp to the current time. keyrecs may be deleted with
111 the keyrec_del() interface.
112 If the keyrec file has been modified, it must be explicitly written or
114 the changes are not saved. keyrec_write() saves the new contents to
115 disk. keyrec_saveas() saves the in-memory keyrec contents to the
116 specified file name, without affecting the original file.
117 keyrec_close() saves the file and close the Perl file handle to the
119 keyrec file. If a keyrec file is no longer wanted to be open, yet the
120 contents should not be saved, keyrec_discard() gets rid of the data,
121 and closes the file handle without saving any modified data.
122
124 The interfaces to the Net::DNS::SEC::Tools::keyrec module are given
125 below.
126 keyrec_add(keyrec_type,keyrec_name,fields)
128 This routine adds a new keyrec to the keyrec file and the internal
129 representation of the file contents. The keyrec is added to both
130 the %keyrecs hash table and the @keyreclines array.
131 keyrec_type specifies the type of the keyrec -- "key" or "zone".
133 keyrec_name is the name of the keyrec. fields is a reference to a
134 hash table that contains the name/value keyrec fields. The keys of
135 the hash table are always converted to lowercase, but the entry
136 values are left as given.
137 The ksklength entry is only added if the value of the keyrec_type
139 field is "kskcur".
140 The zsklength entry is only added if the value of the keyrec_type
142 field is "zsk", "zskcur", "zskpub", or "zsknew".
143 Timestamp fields are added at the end of the keyrec. For key
145 keyrecs, the keyrec_gensecs and keyrec_gendate timestamp fields are
146 added. For zone keyrecs, the keyrec_signsecs and keyrec_signdate
147 timestamp fields are added.
148 If a specified field isn't defined for the keyrec type, the entry
150 isn't added. This prevents zone keyrec data from getting mingled
151 with key keyrec data.
152 A blank line is added after the final line of the new keyrec.
154 After adding all new keyrec entries, the keyrec file is written but
155 is not closed.
156 Return values are:
158 0 success
160 -1 invalid I<krtype>
161 keyrec_close()
163 This interface saves the internal version of the keyrec file
164 (opened with keyrec_read()) and closes the file handle.
165 keyrec_creat(keyrec_file)
167 This interface creates a keyrec file if it does not exist, and
168 truncates the file if it already exists.
169 keyrec_creat() returns 1 if the file was created successfully. It
171 returns 0 if there was an error in creating the file.
172 keyrec_curkrf()
174 This routine returns the name of the keyrec file that is currently
175 in use. This value is the filename passed to keyrec_read() or
176 keyrec_creat(); it is not guaranteed to be either an absolute or
177 relative filename.
178 keyrec_defkrf()
180 This routine returns the default keyrec filename from the DNSSEC-
181 Tools configuration file.
182 keyrec_del(keyrec_name)
184 This routine deletes a keyrec from the keyrec file and the internal
185 representation of the file contents. The keyrec is deleted from
186 both the %keyrecs hash table and the @keyreclines array.
187 Only the keyrec itself is deleted from the file. Any associated
189 comments and blank lines surrounding it are left intact.
190 Return values are:
192 0 successful keyrec deletion
194 -1 invalid krtype (empty string or unknown name)
195 keyrec_delval(keyrec_name, field)
197 This routine deletes the field from the keyrec named by
198 keyrec_name. The keyrec is deleted from both the %keyrecs hash
199 table and the @keyreclines array.
200 Return values are:
202 -1 keyrec_name not the name of an existing keyrec
204 0 field not found in keyrec
205 1 field deleted from keyrec
206 keyrec_discard()
208 This routine removes a keyrec file from use by a program. The
209 internally stored data are deleted and the keyrec file handle is
210 closed. However, modified data are not saved prior to closing the
211 file handle. Thus, modified and new data will be lost.
212 keyrec_exists(keyrec_name)
214 keyrec_exists() returns a boolean indicating if a keyrec exists
215 that has the specified keyrec_name.
216 keyrec_filestat(keyrec_name)
218 keyrec_filestat() checks that a given file might be a reasonable
219 candidate for a DNSSEC-Tools keyrec file. The checks to be
220 performed may be gleaned from the list of return values.
221 Return values are:
223 0 - returned if the tests are all succeed
224 1 - an actual name wasn't given
225 2 - the file does not exist
226 3 - the file is not a regular file
227 4 - the file is not readable
228 5 - the file is empty
229 keyrec_fullrec(keyrec_name)
231 keyrec_fullrec() returns a reference to the keyrec specified in
232 keyrec_name.
233 keyrec_keyfields()
235 This routine returns a list of the recognized fields for a key
236 keyrec.
237 keyrec_keypaths(zonename,keytype)
239 keyrec_keypaths() returns a list of paths to a set of key files for
240 a given zone. The zone is specified in zonename and the type of
241 key is given in keytype.
242 keytype must be one of the following: "kskcur", "kskpub",
244 "kskrev", "kskobs"", "zskcur", "zskpub", "zsknew", "zskobs", "ksk",
245 "zsk", or "all". Case does not matter for the keytype.
246 If keytype is one of the special labels ("ksk", "zsk", or "all")
248 then a set of key paths will be returned. A keytype of "ksk" will
249 return paths to all KSK keys for the zone, a keytype of "zsk" will
250 return paths to all ZSK keys for the zone, and a keytype of "all"
251 will return paths to all keys for the zone,
252 If the given key type is not defined in the given zone's zone
254 keyrec or if the key type is not recognized, then a null set is
255 returned.
256 keyrec_names()
258 This routine returns a list of the keyrec names from the file.
259 keyrec_open(keyrec_file) DEPRECATED
261 This routine used to open an existing DNSSEC-Tools keyrec file.
262 However, this was an unnecessary operation since keyrec_read()
263 would open the file if it wasn't already open.
264 This call will eventually be removed. For now, it calls
266 keyrec_filestat() to check the validity of the specified keyrec
267 file.
268 Return values:
270 1 is the file passes all of keyrec_filestat()'s tests
272 0 is the file fails any of keyrec_filestat()'s tests
273 For backwards compatibility, the success/failure meaning of the
275 return values matches the success/failure meaning of
276 keyrec_open()'s original returns.
277 keyrec_read(keyrec_file)
279 This interface reads the specified keyrec file and parses it into a
280 keyrec hash table and a file contents array. keyrec_read() must be
281 called prior to any of the other Net::DNS::SEC::Tools::keyrec
282 calls. If another keyrec is already open, then it is saved and
283 closed prior to opening the new keyrec.
284 Upon success, keyrec_read() returns the number of keyrecs read from
286 the file.
287 Failure return values:
289 -1 specified I<keyrec> file doesn't exist
291 -2 unable to open I<keyrec> file
292 -3 duplicate I<keyrec> names in file
293 keyrec_recval(keyrec_name,keyrec_field)
295 This routine returns the value of a specified field in a given
296 keyrec. keyrec_name is the name of the particular keyrec to
297 consult. keyrec_field is the field name within that keyrec.
298 For example, the current keyrec file contains the following keyrec:
300 zone "example.com"
302 zonefile "db.example.com"
303 The call:
305 keyrec_recval("example.com","zonefile")
307 will return the value "db.example.com".
309 keyrec_revoke_check(key)
311 This interface checks a revoked KSK's keyrec to determine if it is
312 in or out of its revocation period. The key must be a "kskrev"
313 type key, and it must have "revtime" and "revperiod" fields defined
314 in the keyrec.
315 The determination is made by subtracting the revoke time from the
317 current time. If this is greater than the revocation period, the
318 the key has exceeded the time in which it must be revoked. If not,
319 then it must remain revoked.
320 Return values:
322 1 specified key is outside the revocation period and should be
324 marked as obsolete
325 0 specified key is in the revocation period and should be left
326 revoked
327 -1 error (invalid key type, missing I<keyrec> data)
328 keyrec_saveas(keyrec_file_copy)
330 This interface saves the internal version of the keyrec file
331 (opened with or keyrec_read()) to the file named in the
332 keyrec_file_copy parameter. The new file's file handle is closed,
333 but the original file and the file handle to the original file are
334 not affected.
335 keyrec_setval(keyrec_type,keyrec_name,field,value)
337 Set the value of a name/field pair in a specified keyrec. The file
338 is not written after updating the value. The value is saved in
339 both %keyrecs and in @keyreclines, and the file-modified flag is
340 set.
341 keyrec_type specifies the type of the keyrec. This is only used if
343 a new keyrec is being created by this call. keyrec_name is the
344 name of the keyrec that will be modified. field is the keyrec
345 field which will be modified. value is the new value for the
346 field.
347 Return values are:
349 0 if the creation succeeded
351 -1 invalid type was given
352 keyrec_settime(keyrec_type,keyrec_name)
354 Set the timestamp of a specified keyrec. The file is not written
355 after updating the value. The value is saved in both %keyrecs and
356 in @keyreclines, and the file-modified flag is set. The keyrec's
357 keyrec_signdate and keyrec_signsecs fields are modified.
358 keyrec_write()
360 This interface saves the internal version of the keyrec file
361 (opened with or keyrec_read()). It does not close the file handle.
362 As an efficiency measure, an internal modification flag is checked
363 prior to writing the file. If the program has not modified the
364 contents of the keyrec file, it is not rewritten.
365 keyrec_write() gets an exclusive lock on the keyrec file while
367 writing.
368 keyrec_zonefields()
370 This routine returns a list of the recognized fields for a zone
371 keyrec.
372
374 Signing sets are collections of encryption keys, defined by inclusion
375 in a particular "set" keyrec. The names of the keys are in the
376 keyrec's keys record, which contains the names of the key keyrecs. Due
377 to the way key names are handled, the names in a signing set must not
378 contain spaces.
379 The signing-set-specific interfaces are given below.
381 keyrec_signset_newname(zone_name)
383 keyrec_signset_newname() creates a name for a new signing set. The
384 name will be generated by referencing the lastset field in the
385 keyrec for zone zone_name, if the keyrec has such a field. The set
386 index number (described below) will be incremented and the lastset
387 with the new index number will be returned as the new signing set
388 name. If the zone keyrec does not have a lastset field, then the
389 default set name of signing-set-0 will be used.
390 The set index number is the first number found in the lastset
392 field. It doesn't matter where in the field it is found, the first
393 number will be considered to be the signing set index. The
394 examples below show how this is determined:
395 lastset field index
397 ------------- -----
398 signing-set-0 0
399 signing-0-set 0
400 1-signing-0-set 1
401 signing-88-set-1 88
402 signingset4321 4321
403 keyrec_signset_new(zone,signing_set_name,set_type)
405 keyrec_signset_new() creates the signing set named by
406 signing_set_name for the zone zone. It is given the type type,
407 which must be one of the following: "kskcur", "kskpub", "kskrev",
408 "kskobs", "zskcur", "zskpub", "zsknew", or "zskobs".
409 It returns 1 if the call is successful; 0 if it is not.
411 keyrec_signset_prefix(zone_name)
413 keyrec_signset_prefix() returns the signing set prefix formed by
414 concatenating the zone name and $DEFSETPREFIX. This prefix should
415 be followed by a numeric index.
416 keyrec_signset_addkey(signing_set_name,key_list)
418 keyrec_signset_addkey() adds the keys listed in key_list to the
419 signing set named by signing_set_name. key_list may either be an
420 array or a set or arguments to the routine. The keyrec is created
421 if it does not already exist. It returns 1 if the call is
422 successful; 0 if it is not.
423 keyrec_signset_delkey(signing_set_name,key_name)
425 keyrec_signset_delkey() deletes the key given in key_name to the
426 signing set named by signing_set_name. It returns 1 if the call is
427 successful; 0 if it is not.
428 keyrec_signset_haskey(signing_set_name,key_name)
430 keyrec_signset_haskey() returns a flag indicating if the key
431 specified in key_name is one of the keys in the signing set named
432 by signing_set_name. It returns 1 if the signing set has the key;
433 0 if it does not.
434 keyrec_signset_clear(keyrec_name)
436 keyrec_signset_clear() clears the entire signing set from the
437 keyrec named by keyrec_name. It returns 1 if the call is
438 successful; 0 if it is not.
439 keyrec_signsets()
441 keyrec_signsets() returns the names of the signing sets in the
442 keyrec file. These names are returned in an array.
443 keyrec_signset_keys(keyrec_name,signset_type)
445 keyrec_signset_keys() returns the names of the keys that are
446 members of a given signing set in the keyrec file. The keys are
447 returned in a space-separated string.
448 There are two ways of calling keyrec_signset_keys(). The first
450 method specifies a zone keyrec name and a signing set type. The
451 signing set name is found by referencing the set field in the zone
452 keyrec, then the keys field of that signing set is returned.
453 The second method specifies the signing set directly, and its keys
455 field is returned.
456 Valid signing set types are:
458 kskcur kskpub kskrev kskobs
460 zskcur zskpub zsknew zskobs
461 The following errors are recognized, resulting in an undefined
463 return:
464 keyrec_name is not a defined keyrec
466 signset_type is an invalid signing set type
467 the signing set keyrec is not a set keyrec
468
470 The interfaces described in this section are intended for internal use
471 by the keyrec.pm module. However, there are situations where external
472 entities may have need of them. Use with caution, as misuse may result
473 in damaged or lost keyrec files.
474 keyrec_init()
476 This routine initializes the internal keyrec data. Pending changes
477 will be lost. An open keyrec file handle will remain open, though
478 the data are no longer held internally. A new keyrec file must be
479 read in order to use the keyrec.pm interfaces again.
480 keyrec_newkeyrec(kr_name,kr_type)
482 This interface creates a new keyrec. The keyrec_name and
483 keyrec_hash fields in the keyrec are set to the values of the
484 kr_name and kr_type parameters. kr_type must be either "key" or
485 "zone".
486 Return values are:
488 0 if the creation succeeded
490 -1 if an invalid I<keyrec> type was given
491
493 The following interfaces display information about the currently parsed
494 keyrec file. They are intended to be used for debugging and testing,
495 but may be useful at other times.
496 keyrec_dump_hash()
498 This routine prints the keyrec file as it is stored internally in a
499 hash table. The keyrecs are printed in alphabetical order, with
500 the fields alphabetized for each keyrec. New keyrecs and keyrec
501 fields are alphabetized along with current keyrecs and fields.
502 Comments from the keyrec file are not included with the hash table.
503 keyrec_dump_array()
505 This routine prints the keyrec file as it is stored internally in
506 an array. The keyrecs are printed in the order given in the file,
507 with the fields ordered in the same manner. New keyrecs are
508 appended to the end of the array. keyrec fields added to existing
509 keyrecs are added at the beginning of the keyrec entry. Comments
510 and vertical whitespace are preserved as given in the keyrec file.
511
513 Copyright 2005-2014 SPARTA, Inc. All rights reserved. See the COPYING
514 file included with the DNSSEC-Tools package for details.
515
517 Wayne Morrison, tewok@tislabs.com
518
520 Net::DNS::SEC::Tools::conf(5), Net::DNS::SEC::Tools::keyrec(5)
521perl v5.38.0 2023-07-19 keyrec(3)