1keyrec(3)             User Contributed Perl Documentation            keyrec(3)
2
3
4

NAME

6       Net::DNS::SEC::Tools::keyrec - DNSSEC-Tools keyrec file operations
7

SYNOPSIS

9         use Net::DNS::SEC::Tools::keyrec;
10
11         keyrec_creat("localzone.keyrec");
12         keyrec_open("localzone.keyrec");  (DEPRECATED)
13         $okfile = keyrec_filestat("localzone.keyrec");
14         keyrec_read("localzone.keyrec");
15
16         @krnames = keyrec_names();
17
18         $krec = keyrec_fullrec("example.com");
19         %keyhash = %$krec;
20         $zname = $keyhash{"algorithm"};
21
22         $val = keyrec_recval("example.com","zonefile");
23
24         $exists = keyrec_exists("example.com");
25
26         keyrec_add("zone","example.com",\%zone_krfields);
27         keyrec_add("key","Kexample.com.+005+12345",\%keydata);
28
29         keyrec_del("example.com");
30
31         keyrec_setval("zone","example.com","zonefile","db.example.com");
32
33         keyrec_delval("example.com","kskrev");
34
35         @kskpaths = keyrec_keypaths("example.com","kskcur");
36
37         $obsflag = keyrec_revoke_check("Kexample.com.+005+12345");
38
39         $setname = keyrec_signset_newname("example.com");
40
41         keyrec_signset_new($zone,"example-set-21","zskcur");
42
43         keyrec_signset_addkey("example-keys","Kexample.com+005+12345",
44                                                "Kexample.com+005+54321");
45         keyrec_signset_addkey("example-keys",@keylist);
46
47         keyrec_signset_delkey("example-keys","Kexample.com+005+12345");
48
49         $flag = keyrec_signset_haskey("example-keys","Kexample.com+005+12345");
50
51         keyrec_signset_clear("example-keys","Kexample.com+005+12345");
52
53         @signset = keyrec_signsets();
54
55         $sset_prefix = keyrec_signset_prefix("example.com");
56
57         keyrec_settime("zone","example.com");
58         keyrec_settime("set","signing-set-42");
59         keyrec_settime("key","Kexample.com.+005+76543");
60
61         @keyfields = keyrec_keyfields();
62         @zonefields = keyrec_zonefields();
63
64         keyrec_write();
65         keyrec_saveas("filecopy.krf);
66         keyrec_close();
67         keyrec_discard();
68
69         $current_krf = keyrec_curkrf();
70         $default_krf = keyrec_defkrf();
71

DESCRIPTION

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
79       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
85           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
97       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
107       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
113       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
118       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

KEYREC INTERFACES

124       The interfaces to the Net::DNS::SEC::Tools::keyrec module are given
125       below.
126
127       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
132           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
138           The ksklength entry is only added if the value of the keyrec_type
139           field is "kskcur".
140
141           The zsklength entry is only added if the value of the keyrec_type
142           field is "zsk", "zskcur", "zskpub", or "zsknew".
143
144           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
149           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
153           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
157           Return values are:
158
159               0 success
160               -1 invalid I<krtype>
161
162       keyrec_close()
163           This interface saves the internal version of the keyrec file
164           (opened with keyrec_read()) and closes the file handle.
165
166       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
170           keyrec_creat() returns 1 if the file was created successfully.  It
171           returns 0 if there was an error in creating the file.
172
173       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
179       keyrec_defkrf()
180           This routine returns the default keyrec filename from the DNSSEC-
181           Tools configuration file.
182
183       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
188           Only the keyrec itself is deleted from the file.  Any associated
189           comments and blank lines surrounding it are left intact.
190
191           Return values are:
192
193                0 successful keyrec deletion
194               -1 invalid krtype (empty string or unknown name)
195
196       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
201           Return values are:
202
203               -1 keyrec_name not the name of an existing keyrec
204                0 field not found in keyrec
205                1 field deleted from keyrec
206
207       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
213       keyrec_exists(keyrec_name)
214           keyrec_exists() returns a boolean indicating if a keyrec exists
215           that has the specified keyrec_name.
216
217       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
222           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
230       keyrec_fullrec(keyrec_name)
231           keyrec_fullrec() returns a reference to the keyrec specified in
232           keyrec_name.
233
234       keyrec_keyfields()
235           This routine returns a list of the recognized fields for a key
236           keyrec.
237
238       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
243           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
247           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
253           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
257       keyrec_names()
258           This routine returns a list of the keyrec names from the file.
259
260       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
265           This call will eventually be removed.  For now, it calls
266           keyrec_filestat() to check the validity of the specified keyrec
267           file.
268
269           Return values:
270
271               1 is the file passes all of keyrec_filestat()'s tests
272               0 is the file fails any of keyrec_filestat()'s tests
273
274           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
278       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
285           Upon success, keyrec_read() returns the number of keyrecs read from
286           the file.
287
288           Failure return values:
289
290               -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
294       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
299           For example, the current keyrec file contains the following keyrec:
300
301               zone        "example.com"
302                           zonefile        "db.example.com"
303
304           The call:
305
306               keyrec_recval("example.com","zonefile")
307
308           will return the value "db.example.com".
309
310       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
316           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
321           Return values:
322
323                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
329       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
336       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
342           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
348           Return values are:
349
350               0 if the creation succeeded
351               -1 invalid type was given
352
353       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
359       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
366           keyrec_write() gets an exclusive lock on the keyrec file while
367           writing.
368
369       keyrec_zonefields()
370           This routine returns a list of the recognized fields for a zone
371           keyrec.
372

KEYREC SIGNING-SET INTERFACES

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
380       The signing-set-specific interfaces are given below.
381
382       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
391           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
396               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
404       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
410           It returns 1 if the call is successful; 0 if it is not.
411
412       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
417       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
424       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
429       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
435       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
440       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
444       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
449           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
454           The second method specifies the signing set directly, and its keys
455           field is returned.
456
457           Valid signing set types are:
458
459               kskcur        kskpub        kskrev        kskobs
460               zskcur        zskpub        zsknew        zskobs
461
462           The following errors are recognized, resulting in an undefined
463           return:
464
465               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

KEYREC INTERNAL INTERFACES

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
475       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
481       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
487           Return values are:
488
489               0 if the creation succeeded
490               -1 if an invalid I<keyrec> type was given
491

KEYREC DEBUGGING INTERFACES

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
497       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
504       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

AUTHOR

517       Wayne Morrison, tewok@tislabs.com
518

SEE ALSO

520       Net::DNS::SEC::Tools::conf(5), Net::DNS::SEC::Tools::keyrec(5)
521
522
523
524perl v5.38.0                      2023-07-19                         keyrec(3)
Impressum