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 keyrec_settime("zone","example.com");
56 keyrec_settime("set","signing-set-42");
57 keyrec_settime("key","Kexample.com.+005+76543");
58 @keyfields = keyrec_keyfields();
60 @zonefields = keyrec_zonefields();
61 keyrec_write();
63 keyrec_saveas("filecopy.krf);
64 keyrec_close();
65 keyrec_discard();
66 $current_krf = keyrec_curkrf();
68 $default_krf = keyrec_defkrf();
69
71 The Net::DNS::SEC::Tools::keyrec module manipulates the contents of a
72 DNSSEC-Tools keyrec file. keyrec files contain data about zones signed
73 by and keys generated by the DNSSEC-Tools programs. Module interfaces
74 exist for looking up keyrec records, creating new records, and
75 modifying existing records.
76 A keyrec file is organized in sets of keyrec records. Each keyrec must
78 be either of key type or zone type. Key keyrecs describe how
79 encryption keys were generated, zone keyrecs describe how zones were
80 signed. A keyrec consists of a set of keyword/value entries. The
81 following is an example of a key keyrec:
82 key "Kexample.com.+005+30485"
84 zonename "example.com"
85 keyrec_type "kskcur"
86 algorithm "rsasha1"
87 random "/dev/urandom"
88 ksklength "2048"
89 ksklife "15768000"
90 revperiod "3888000"
91 revtime "1103277532"
92 keyrec_gensecs "1101183727"
93 keyrec_gendate "Tue Nov 23 04:22:07 2004"
94 The first step in using this module must be to create a new keyrec file
96 or open and read an existing one. The keyrec_creat() interface creates
97 a keyrec file if it does not exist. The keyrec_read() interface opens
98 and reads the file, then parses it into an internal format. The file's
99 records are copied into a hash table (for easy and fast reference by
100 the Net::DNS::SEC::Tools::keyrec routines) and in an array (for
101 preserving formatting and comments.) The keyrec_filestat() interface
102 may be used check that the given file may be a keyrec file, though it
103 doesn't check the file's contents.
104 After the file has been read, the contents are referenced using
106 keyrec_fullrec() and keyrec_recval(). The keyrec contents are modified
107 using keyrec_add(), and keyrec_setval(). keyrec_settime() will update
108 a keyrec's timestamp to the current time. keyrecs may be deleted with
109 the keyrec_del() interface.
110 If the keyrec file has been modified, it must be explicitly written or
112 the changes are not saved. keyrec_write() saves the new contents to
113 disk. keyrec_saveas() saves the in-memory keyrec contents to the
114 specified file name, without affecting the original file.
115 keyrec_close() saves the file and close the Perl file handle to the
117 keyrec file. If a keyrec file is no longer wanted to be open, yet the
118 contents should not be saved, keyrec_discard() gets rid of the data,
119 and closes the file handle without saving any modified data.
120
122 The interfaces to the Net::DNS::SEC::Tools::keyrec module are given
123 below.
124 keyrec_add(keyrec_type,keyrec_name,fields)
126 This routine adds a new keyrec to the keyrec file and the internal
127 representation of the file contents. The keyrec is added to both
128 the %keyrecs hash table and the @keyreclines array.
129 keyrec_type specifies the type of the keyrec -- "key" or "zone".
131 keyrec_name is the name of the keyrec. fields is a reference to a
132 hash table that contains the name/value keyrec fields. The keys of
133 the hash table are always converted to lowercase, but the entry
134 values are left as given.
135 The ksklength entry is only added if the value of the keyrec_type
137 field is "kskcur".
138 The zsklength entry is only added if the value of the keyrec_type
140 field is "zsk", "zskcur", "zskpub", or "zsknew".
141 Timestamp fields are added at the end of the keyrec. For key
143 keyrecs, the keyrec_gensecs and keyrec_gendate timestamp fields are
144 added. For zone keyrecs, the keyrec_signsecs and keyrec_signdate
145 timestamp fields are added.
146 If a specified field isn't defined for the keyrec type, the entry
148 isn't added. This prevents zone keyrec data from getting mingled
149 with key keyrec data.
150 A blank line is added after the final line of the new keyrec.
152 After adding all new keyrec entries, the keyrec file is written but
153 is not closed.
154 Return values are:
156 0 success
158 -1 invalid I<krtype>
159 keyrec_close()
161 This interface saves the internal version of the keyrec file
162 (opened with keyrec_read()) and closes the file handle.
163 keyrec_creat(keyrec_file)
165 This interface creates a keyrec file if it does not exist, and
166 truncates the file if it already exists.
167 keyrec_creat() returns 1 if the file was created successfully. It
169 returns 0 if there was an error in creating the file.
170 keyrec_curkrf()
172 This routine returns the name of the keyrec file that is currently
173 in use. This value is the filename passed to keyrec_read() or
174 keyrec_creat(); it is not guaranteed to be either an absolute or
175 relative filename.
176 keyrec_defkrf()
178 This routine returns the default keyrec filename from the DNSSEC-
179 Tools configuration file.
180 keyrec_del(keyrec_name)
182 This routine deletes a keyrec from the keyrec file and the internal
183 representation of the file contents. The keyrec is deleted from
184 both the %keyrecs hash table and the @keyreclines array.
185 Only the keyrec itself is deleted from the file. Any associated
187 comments and blank lines surrounding it are left intact.
188 Return values are:
190 0 successful keyrec deletion
192 -1 invalid krtype (empty string or unknown name)
193 keyrec_delval(keyrec_name, field)
195 This routine deletes the field from the keyrec named by
196 keyrec_name. The keyrec is deleted from both the %keyrecs hash
197 table and the @keyreclines array.
198 Return values are:
200 -1 keyrec_name not the name of an existing keyrec
202 0 field not found in keyrec
203 1 field deleted from keyrec
204 keyrec_discard()
206 This routine removes a keyrec file from use by a program. The
207 internally stored data are deleted and the keyrec file handle is
208 closed. However, modified data are not saved prior to closing the
209 file handle. Thus, modified and new data will be lost.
210 keyrec_exists(keyrec_name)
212 keyrec_exists() returns a boolean indicating if a keyrec exists
213 that has the specified keyrec_name.
214 keyrec_filestat(keyrec_name)
216 keyrec_filestat() checks that a given file might be a reasonable
217 candidate for a DNSSEC-Tools keyrec file. The checks to be
218 performed may be gleaned from the list of return values.
219 Return values are:
221 0 - returned if the tests are all succeed
222 1 - an actual name wasn't given
223 2 - the file does not exist
224 3 - the file is not a regular file
225 4 - the file is not readable
226 5 - the file is empty
227 keyrec_fullrec(keyrec_name)
229 keyrec_fullrec() returns a reference to the keyrec specified in
230 keyrec_name.
231 keyrec_keyfields()
233 This routine returns a list of the recognized fields for a key
234 keyrec.
235 keyrec_keypaths(zonename,keytype)
237 keyrec_keypaths() returns a list of paths to a set of key files for
238 a given zone. The zone is specified in zonename and the type of
239 key is given in keytype.
240 keytype must be one of the following: "kskcur", "kskpub",
242 "kskrev", "kskobs"", "zskcur", "zskpub", "zsknew", "zskobs", "ksk",
243 "zsk", or "all". Case does not matter for the keytype.
244 If keytype is one of the special labels ("ksk", "zsk", or "all")
246 then a set of key paths will be returned. A keytype of "ksk" will
247 return paths to all KSK keys for the zone, a keytype of "zsk" will
248 return paths to all ZSK keys for the zone, and a keytype of "all"
249 will return paths to all keys for the zone,
250 If the given key type is not defined in the given zone's zone
252 keyrec or if the key type is not recognized, then a null set is
253 returned.
254 keyrec_names()
256 This routine returns a list of the keyrec names from the file.
257 keyrec_open(keyrec_file) DEPRECATED
259 This routine used to open an existing DNSSEC-Tools keyrec file.
260 However, this was an unnecessary operation since keyrec_read()
261 would open the file if it wasn't already open.
262 This call will eventually be removed. For now, it calls
264 keyrec_filestat() to check the validity of the specified keyrec
265 file.
266 Return values:
268 1 is the file passes all of keyrec_filestat()'s tests
270 0 is the file fails any of keyrec_filestat()'s tests
271 For backwards compatibility, the success/failure meaning of the
273 return values matches the success/failure meaning of
274 keyrec_open()'s original returns.
275 keyrec_read(keyrec_file)
277 This interface reads the specified keyrec file and parses it into a
278 keyrec hash table and a file contents array. keyrec_read() must be
279 called prior to any of the other Net::DNS::SEC::Tools::keyrec
280 calls. If another keyrec is already open, then it is saved and
281 closed prior to opening the new keyrec.
282 Upon success, keyrec_read() returns the number of keyrecs read from
284 the file.
285 Failure return values:
287 -1 specified I<keyrec> file doesn't exist
289 -2 unable to open I<keyrec> file
290 -3 duplicate I<keyrec> names in file
291 keyrec_recval(keyrec_name,keyrec_field)
293 This routine returns the value of a specified field in a given
294 keyrec. keyrec_name is the name of the particular keyrec to
295 consult. keyrec_field is the field name within that keyrec.
296 For example, the current keyrec file contains the following keyrec:
298 zone "example.com"
300 zonefile "db.example.com"
301 The call:
303 keyrec_recval("example.com","zonefile")
305 will return the value "db.example.com".
307 keyrec_revoke_check(key)
309 This interface checks a revoked KSK's keyrec to determine if it is
310 in or out of its revocation period. The key must be a "kskrev"
311 type key, and it must have "revtime" and "revperiod" fields defined
312 in the keyrec.
313 The determination is made by subtracting the revoke time from the
315 current time. If this is greater than the revocation period, the
316 the key has exceeded the time in which it must be revoked. If not,
317 then it must remain revoked.
318 Return values:
320 1 specified key is outside the revocation period and should be
322 marked as obsolete
323 0 specified key is in the revocation period and should be left
324 revoked
325 -1 error (invalid key type, missing I<keyrec> data)
326 keyrec_saveas(keyrec_file_copy)
328 This interface saves the internal version of the keyrec file
329 (opened with or keyrec_read()) to the file named in the
330 keyrec_file_copy parameter. The new file's file handle is closed,
331 but the original file and the file handle to the original file are
332 not affected.
333 keyrec_setval(keyrec_type,keyrec_name,field,value)
335 Set the value of a name/field pair in a specified keyrec. The file
336 is not written after updating the value. The value is saved in
337 both %keyrecs and in @keyreclines, and the file-modified flag is
338 set.
339 keyrec_type specifies the type of the keyrec. This is only used if
341 a new keyrec is being created by this call. keyrec_name is the
342 name of the keyrec that will be modified. field is the keyrec
343 field which will be modified. value is the new value for the
344 field.
345 Return values are:
347 0 if the creation succeeded
349 -1 invalid type was given
350 keyrec_settime(keyrec_type,keyrec_name)
352 Set the timestamp of a specified keyrec. The file is not written
353 after updating the value. The value is saved in both %keyrecs and
354 in @keyreclines, and the file-modified flag is set. The keyrec's
355 keyrec_signdate and keyrec_signsecs fields are modified.
356 keyrec_write()
358 This interface saves the internal version of the keyrec file
359 (opened with or keyrec_read()). It does not close the file handle.
360 As an efficiency measure, an internal modification flag is checked
361 prior to writing the file. If the program has not modified the
362 contents of the keyrec file, it is not rewritten.
363 keyrec_write() gets an exclusive lock on the keyrec file while
365 writing.
366 keyrec_zonefields()
368 This routine returns a list of the recognized fields for a zone
369 keyrec.
370
372 Signing sets are collections of encryption keys, defined by inclusion
373 in a particular "set" keyrec. The names of the keys are in the
374 keyrec's keys record, which contains the names of the key keyrecs. Due
375 to the way key names are handled, the names in a signing set must not
376 contain spaces.
377 The signing-set-specific interfaces are given below.
379 keyrec_signset_newname(zone_name)
381 keyrec_signset_newname() creates a name for a new signing set. The
382 name will be generated by referencing the lastset field in the
383 keyrec for zone zone_name, if the keyrec has such a field. The set
384 index number (described below) will be incremented and the lastset
385 with the new index number will be returned as the new signing set
386 name. If the zone keyrec does not have a lastset field, then the
387 default set name of signing-set-0 will be used.
388 The set index number is the first number found in the lastset
390 field. It doesn't matter where in the field it is found, the first
391 number will be considered to be the signing set index. The
392 examples below show how this is determined:
393 lastset field index
395 ------------- -----
396 signing-set-0 0
397 signing-0-set 0
398 1-signing-0-set 1
399 signing-88-set-1 88
400 signingset4321 4321
401 keyrec_signset_new(zone,signing_set_name,set_type)
403 keyrec_signset_new() creates the signing set named by
404 signing_set_name for the zone zone. It is given the type type,
405 which must be one of the following: "kskcur", "kskpub", "kskrev",
406 "kskobs", "zskcur", "zskpub", "zsknew", or "zskobs".
407 It returns 1 if the call is successful; 0 if it is not.
409 keyrec_signset_addkey(signing_set_name,key_list)
411 keyrec_signset_addkey() adds the keys listed in key_list to the
412 signing set named by signing_set_name. key_list may either be an
413 array or a set or arguments to the routine. The keyrec is created
414 if it does not already exist. It returns 1 if the call is
415 successful; 0 if it is not.
416 keyrec_signset_delkey(signing_set_name,key_name)
418 keyrec_signset_delkey() deletes the key given in key_name to the
419 signing set named by signing_set_name. It returns 1 if the call is
420 successful; 0 if it is not.
421 keyrec_signset_haskey(signing_set_name,key_name)
423 keyrec_signset_haskey() returns a flag indicating if the key
424 specified in key_name is one of the keys in the signing set named
425 by signing_set_name. It returns 1 if the signing set has the key;
426 0 if it does not.
427 keyrec_signset_clear(keyrec_name)
429 keyrec_signset_clear() clears the entire signing set from the
430 keyrec named by keyrec_name. It returns 1 if the call is
431 successful; 0 if it is not.
432 keyrec_signsets()
434 keyrec_signsets() returns the names of the signing sets in the
435 keyrec file. These names are returned in an array.
436 keyrec_signset_keys(keyrec_name,signset_type)
438 keyrec_signset_keys() returns the names of the keys that are
439 members of a given signing set in the keyrec file. The keys are
440 returned in a space-separated string.
441 There are two ways of calling keyrec_signset_keys(). The first
443 method specifies a zone keyrec name and a signing set type. The
444 signing set name is found by referencing the set field in the zone
445 keyrec, then the keys field of that signing set is returned.
446 The second method specifies the signing set directly, and its keys
448 field is returned.
449 Valid signing set types are:
451 kskcur kskpub kskrev kskobs
453 zskcur zskpub zsknew zskobs
454 The following errors are recognized, resulting in an undefined
456 return:
457 keyrec_name is not a defined keyrec
459 signset_type is an invalid signing set type
460 the signing set keyrec is not a set keyrec
461
463 The interfaces described in this section are intended for internal use
464 by the keyrec.pm module. However, there are situations where external
465 entities may have need of them. Use with caution, as misuse may result
466 in damaged or lost keyrec files.
467 keyrec_init()
469 This routine initializes the internal keyrec data. Pending changes
470 will be lost. An open keyrec file handle will remain open, though
471 the data are no longer held internally. A new keyrec file must be
472 read in order to use the keyrec.pm interfaces again.
473 keyrec_newkeyrec(kr_name,kr_type)
475 This interface creates a new keyrec. The keyrec_name and
476 keyrec_hash fields in the keyrec are set to the values of the
477 kr_name and kr_type parameters. kr_type must be either "key" or
478 "zone".
479 Return values are:
481 0 if the creation succeeded
483 -1 if an invalid I<keyrec> type was given
484
486 The following interfaces display information about the currently parsed
487 keyrec file. They are intended to be used for debugging and testing,
488 but may be useful at other times.
489 keyrec_dump_hash()
491 This routine prints the keyrec file as it is stored internally in a
492 hash table. The keyrecs are printed in alphabetical order, with
493 the fields alphabetized for each keyrec. New keyrecs and keyrec
494 fields are alphabetized along with current keyrecs and fields.
495 Comments from the keyrec file are not included with the hash table.
496 keyrec_dump_array()
498 This routine prints the keyrec file as it is stored internally in
499 an array. The keyrecs are printed in the order given in the file,
500 with the fields ordered in the same manner. New keyrecs are
501 appended to the end of the array. keyrec fields added to existing
502 keyrecs are added at the beginning of the keyrec entry. Comments
503 and vertical whitespace are preserved as given in the keyrec file.
504
506 Copyright 2005-2011 SPARTA, Inc. All rights reserved. See the COPYING
507 file included with the DNSSEC-Tools package for details.
508
510 Wayne Morrison, tewok@users.sourceforge.net
511
513 Net::DNS::SEC::Tools::conf(5), Net::DNS::SEC::Tools::keyrec(5)
514perl v5.12.4 2011-09-28 keyrec(3)