keyrec(3)

📦
version 2.2.3 · 3 versions
, in arch rolling

keyrec(3) — like, the Net::DNS::SEC::Tools::keyrec manual page, bestie 💖

It's from User Contributed Perl Documentation, and it's literally all about DNSSEC-Tools keyrec file operations. Buckle up 🎀

✨ NAME ✨

Net::DNS::SEC::Tools::keyrec — DNSSEC-Tools keyrec file operations. That's the whole vibe. 💅

🌸 SYNOPSIS 🌸

okay so here's the whole group chat of functions, no cap:

  use Net::DNS::SEC::Tools::keyrec;

  keyrec_creat("localzone.keyrec");
  keyrec_open("localzone.keyrec");  (DEPRECATED)
  $okfile = keyrec_filestat("localzone.keyrec");
  keyrec_read("localzone.keyrec");

  @krnames = keyrec_names();

  $krec = keyrec_fullrec("example.com");
  %keyhash = %$krec;
  $zname = $keyhash{"algorithm"};

  $val = keyrec_recval("example.com","zonefile");

  $exists = keyrec_exists("example.com");

  keyrec_add("zone","example.com",\%zone_krfields);
  keyrec_add("key","Kexample.com.+005+12345",\%keydata);

  keyrec_del("example.com");

  keyrec_setval("zone","example.com","zonefile","db.example.com");

  keyrec_delval("example.com","kskrev");

  @kskpaths = keyrec_keypaths("example.com","kskcur");

  $obsflag = keyrec_revoke_check("Kexample.com.+005+12345");

  $setname = keyrec_signset_newname("example.com");

  keyrec_signset_new($zone,"example-set-21","zskcur");

  keyrec_signset_addkey("example-keys","Kexample.com+005+12345",
                                         "Kexample.com+005+54321");
  keyrec_signset_addkey("example-keys",@keylist);

  keyrec_signset_delkey("example-keys","Kexample.com+005+12345");

  $flag = keyrec_signset_haskey("example-keys","Kexample.com+005+12345");

  keyrec_signset_clear("example-keys","Kexample.com+005+12345");

  @signset = keyrec_signsets();

  $sset_prefix = keyrec_signset_prefix("example.com");

  keyrec_settime("zone","example.com");
  keyrec_settime("set","signing-set-42");
  keyrec_settime("key","Kexample.com.+005+76543");

  @keyfields = keyrec_keyfields();
  @zonefields = keyrec_zonefields();

  keyrec_write();
  keyrec_saveas("filecopy.krf);
  keyrec_close();
  keyrec_discard();

  $current_krf = keyrec_curkrf();
  $default_krf = keyrec_defkrf();
yes, keyrec_open("localzone.keyrec"); (DEPRECATED) is literally deprecated — it's marked right there in the synopsis, bestie. Don't @ me. 🙈

🦋 DESCRIPTION 🦋

The Net::DNS::SEC::Tools::keyrec module manipulates the contents of a DNSSEC-Tools keyrec file. keyrec files contain data about zones signed by and keys generated by the DNSSEC-Tools programs. Module interfaces exist for looking up keyrec records, creating new records, and modifying existing records. Slay. 👑

A keyrec file is organized in sets of keyrec records. Each keyrec must be either of key type or zone type. Key keyrecs describe how encryption keys were generated, zone keyrecs describe how zones were signed. A keyrec consists of a set of keyword/value entries. The following is an example of a key keyrec:

key     "Kexample.com.+005+30485"
      zonename        "example.com"
      keyrec_type     "kskcur"
      algorithm       "rsasha1"
      random          "/dev/urandom"
      ksklength       "2048"
      ksklife         "15768000"
      revperiod       "3888000"
      revtime         "1103277532"
      keyrec_gensecs  "1101183727"
      keyrec_gendate  "Tue Nov 23 04:22:07 2004"

The first step in using this module (like, literally the first step, don't skip it 💀) must be to create a new keyrec file or open and read an existing one.

  • keyrec_creat() creates a keyrec file if it does not exist.
  • keyrec_read() opens and reads the file, then parses it into an internal format. The file's records are copied into a hash table (for easy and fast reference by the Net::DNS::SEC::Tools::keyrec routines) and in an array (for preserving formatting and comments).
  • keyrec_filestat() may be used check that the given file may be a keyrec file, though it doesn't check the file's contents. (so it's giving vibe check, not content moderation 🫶)

After the file has been read, the contents are referenced using keyrec_fullrec() and keyrec_recval(). The keyrec contents are modified using keyrec_add(), and keyrec_setval(). keyrec_settime() will update a keyrec's timestamp to the current time. keyrecs may be deleted with the keyrec_del() interface.

⚠️ important, bestie: if the keyrec file has been modified, it must be explicitly written or the changes are not saved. Like, no cap, they just vanish. 😭
  • keyrec_write() saves the new contents to disk.
  • keyrec_saveas() saves the in-memory keyrec contents to the specified file name, without affecting the original file.

keyrec_close() saves the file and close the Perl file handle to the keyrec file. If a keyrec file is no longer wanted to be open, yet the contents should not be saved, keyrec_discard() gets rid of the data, and closes the file handle without saving any modified data. iconic cleanup behavior, honestly ✨

💖 KEYREC INTERFACES 💖

okay bestie, buckle up — this is the whole roster of calls the Net::DNS::SEC::Tools::keyrec module hands you. every last one of them, no skips. 🎀

🌸 keyrec_add(keyrec_type,keyrec_name,fields)

this one adds a brand-new keyrec into the keyrec file and into the internal version of the file's contents. it gets dropped into both the %keyrecs hash table and the @keyreclines array. two places, one keyrec, slay. ✨

here's the tea on the arguments:

  • keyrec_type — tells you what kind of keyrec this is. it's either "key" or "zone".
  • keyrec_name — the name of the keyrec. iconic, self-explanatory.
  • fields — a reference to a hash table holding the name/value keyrec fields. heads up: the keys of that hash table are always converted to lowercase, but the entry values are left exactly as you gave them. no touchy. 🫶

now, some conditional little gremlins in here:

  • the ksklength entry is only added if the keyrec_type field's value is "kskcur".
  • the zsklength entry is only added if the keyrec_type field's value is "zsk", "zskcur", "zskpub", or "zsknew".

timestamp fields get tacked on at the end of the keyrec:

  • for key keyrecs, the keyrec_gensecs and keyrec_gendate timestamp fields are added.
  • for zone keyrecs, the keyrec_signsecs and keyrec_signdate timestamp fields are added.

and if you hand it a field that isn't defined for that particular keyrec type? it just doesn't get added. periodt. that's literally the whole point — it keeps zone keyrec data from getting all mingled up with key keyrec data. 💅

one blank line gets added after the final line of the new keyrec. and after all the new keyrec entries are in, the keyrec file gets written — but not closed. 😌

return values, bestie:

    0 success
   -1 invalid krtype

🦋 keyrec_close()

saves the internal version of the keyrec file (the one you opened with keyrec_read()) and closes the file handle. that's it. clean exit, no drama. 🌈

🎀 keyrec_creat(keyrec_file)

creates a keyrec file if it doesn't already exist, and truncates it if it does. (yes, truncates. be normal about it. 💀)

  • returns 1 if the file was created successfully.
  • returns 0 if there was an error creating the file.

⭐ keyrec_curkrf()

returns the name of the keyrec file currently in use — i.e. the filename you passed to keyrec_read() or keyrec_creat(). and no, it is not guaranteed to be either an absolute or a relative filename. it's just whatever you fed it. don't @ me. 🙈

🧚 keyrec_defkrf()

returns the default keyrec filename pulled from the DNSSEC-Tools configuration file. the factory setting, if you will. ✨

💜 keyrec_del(keyrec_name)

deletes a keyrec from the keyrec file and from the internal representation of the file contents — out of both the %keyrecs hash table and the @keyreclines array. bye bestie 👋

important caveat though: only the keyrec itself is deleted. any associated comments and blank lines hanging around it are left completely intact. it does not clean up after itself.

return values:

    0 successful keyrec deletion
   -1 invalid krtype (empty string or unknown name)

🍓 keyrec_delval(keyrec_name, field)

deletes the field from the keyrec named by keyrec_name. and yup, it's deleted from both the %keyrecs hash table and the @keyreclines array.

return values:

   -1 keyrec_name not the name of an existing keyrec
    0 field not found in keyrec
    1 field deleted from keyrec

💀 keyrec_discard()

removes a keyrec file from use by a program. the internally stored data get deleted and the keyrec file handle gets closed.

⚠️ but listen: modified data are not saved before the file handle is closed. so all your modified and new data? gone. lost. evaporated. this is the "I didn't save my Word doc" of interfaces. 😭

🌟 keyrec_exists(keyrec_name)

returns a boolean telling you whether a keyrec with the specified keyrec_name exists. simple. boolean. yes/no. iykyk. 💅

🔥 keyrec_filestat(keyrec_name)

checks that a given file might be a reasonable candidate for a DNSSEC-Tools keyrec file. the actual checks it runs are basically spelled out in the return values, so:

    0 - returned if the tests are all succeed
    1 - an actual name wasn't given
    2 - the file does not exist
    3 - the file is not a regular file
    4 - the file is not readable
    5 - the file is empty

🌈 keyrec_fullrec(keyrec_name)

returns a reference to the keyrec specified in keyrec_name. just the ref, not a copy. handle with care, bestie. 🫶

🎀 keyrec_keyfields()

returns a list of the recognized fields for a key keyrec. that's it. that's the whole function. 💖

🌸 keyrec_keypaths(zonename,keytype)

returns a list of paths to a set of key files for a given zone. the zone goes in zonename, and the type of key goes in keytype.

keytype has to be one of these:

"kskcur", "kskpub", "kskrev", "kskobs"", "zskcur", "zskpub", "zsknew",
"zskobs", "ksk", "zsk", or "all"

case does not matter for keytype. lowercase, uppercase, chaos case — it's all fine. 🦋

now, if keytype is one of the special labels ("ksk", "zsk", or "all"), you get a whole set of key paths back:

  • "ksk" → paths to all KSK keys for the zone
  • "zsk" → paths to all ZSK keys for the zone
  • "all" → paths to all keys for the zone

and if the given key type isn't defined in that zone's zone keyrec, or the key type just isn't recognized at all? you get a null set back. nothing. zilch. 🙈

👑 keyrec_names()

returns a list of the keyrec names from the file. name haul. 💅

💀 keyrec_open(keyrec_file) DEPRECATED

so this one used to open an existing DNSSEC-Tools keyrec file. but like — that was an unnecessary operation, because keyrec_read() would open the file anyway if it wasn't already open. so it's redundant. it's giving legacy code.

⚠️ this call will eventually be removed. for now, it just calls keyrec_filestat() to check the validity of the specified keyrec file.

return values:

  • 1 if the file passes all of keyrec_filestat()'s tests
  • 0 if the file fails any of keyrec_filestat()'s tests

and for backwards compatibility, the success/failure meaning of the return values matches the success/failure meaning of keyrec_open()'s original returns. so old code keeps working. we love a graceful exit. 🫶

⭐ keyrec_read(keyrec_file)

this one reads the specified keyrec file and parses it into a keyrec hash table and a file contents array.

big deal alert: keyrec_read() must be called prior to any of the other Net::DNS::SEC::Tools::keyrec calls. it's the prerequisite. the opening act. and if another keyrec is already open when you call it, that one gets saved and closed before the new one opens. 😌

on success, keyrec_read() returns the number of keyrecs read from the file. 🔥

failure return values:

   -1 specified keyrec file doesn't exist
   -2 unable to open keyrec file
   -3 duplicate keyrec names in file

🍓 keyrec_recval(keyrec_name,keyrec_field)

returns the value of a specified field inside a given keyrec. keyrec_name is the name of the particular keyrec you want to consult, and keyrec_field is the field name inside that keyrec.

for example, say the current keyrec file contains this keyrec:

    zone        "example.com"
                zonefile        "db.example.com"

then this call:

    keyrec_recval("example.com","zonefile")

will return the value "db.example.com". look at it go. ✨

🧚 keyrec_revoke_check(key)

checks a revoked KSK's keyrec to figure out if it's in or out of its revocation period. the key must be a "kskrev" type key, and it must have "revtime" and "revperiod" fields defined in the keyrec.

the determination is made by subtracting the revoke time from the current time:

  • if that result is greater than the revocation period, the key has exceeded the time in which it must be revoked.
  • if not, then it must remain revoked.

return values:

    1 specified key is outside the revocation period and should be
      marked as obsolete
    0 specified key is in the revocation period and should be left
      revoked
   -1 error (invalid key type, missing keyrec data)

💜 keyrec_saveas(keyrec_file_copy)

saves the internal version of the keyrec file (opened with or keyrec_read()) to the file named in the keyrec_file_copy parameter. the new file's file handle gets closed, but the original file — and the file handle to that original file — are not affected. copy, not move. 💅

🌟 keyrec_setval(keyrec_type,keyrec_name,field,value)

sets the value of a name/field pair in a specified keyrec. the file is not written after the value is updated. the value is saved in both %keyrecs and in @keyreclines, and the file-modified flag gets set. 🔥

the args:

  • keyrec_type — the type of the keyrec. this is only used if a new keyrec is being created by this call.
  • keyrec_name — the name of the keyrec that will be modified.
  • field — the keyrec field that will be modified.
  • value — the new value for the field.

return values:

    0 if the creation succeeded
   -1 invalid type was given

🌈 keyrec_settime(keyrec_type,keyrec_name)

sets the timestamp of a specified keyrec. like keyrec_setval(), the file is not written after updating the value. the value is saved in both %keyrecs and in @keyreclines, and the file-modified flag is set.

specifically, the keyrec's keyrec_signdate and keyrec_signsecs fields are the ones that get modified. ⏰

🎀 keyrec_write()

saves the internal version of the keyrec file (opened with or keyrec_read()). it does not close the file handle. keep that handle, bestie.

as an efficiency measure, an internal modification flag gets checked before writing. so if your program hasn't modified the contents of the keyrec file, it doesn't get rewritten. no wasted writes. we love efficiency. ✨

also: keyrec_write() gets an exclusive lock on the keyrec file while writing. respect the lock. 🔒

🦋 keyrec_zonefields()

returns a list of the recognized fields for a zone keyrec. the zone counterpart to keyrec_keyfields(), obviously. 💖

💅 KEYREC SIGNING-SET INTERFACES 💅

Okay so signing sets are collections of encryption keys, defined by inclusion in a particular "set" keyrec. The names of the keys live in the keyrec’s keys record, which contains the names of the key keyrecs. Due to the way key names are handled, names in a signing set must not contain spaces. 🚨 No cap, that’s a hard rule. periodt.

The signing-set-specific interfaces are right below, bestie:

keyrec_signset_newname(zone_name)

keyrec_signset_newname() creates a name for a new signing set. The name will be generated by referencing the lastset field in the keyrec for zone zone_name, if the keyrec has such a field. The set index number (described below) will be incremented, and the lastset with the new index number will be returned as the new signing set name. If the zone keyrec does not have a lastset field, then the default set name of signing-set-0 will be used.

The set index number is the first number found in the lastset field. It doesn’t matter where in the field it is found — the first number will be considered to be the signing set index. The examples below show how this is determined:

lastset field               index
-------------               -----
signing-set-0                  0
signing-0-set                  0
1-signing-0-set                1
signing-88-set-1              88
signingset4321              4321

keyrec_signset_new(zone,signing_set_name,set_type)

keyrec_signset_new() creates the signing set named by signing_set_name for the zone zone. The set_type argument must be one of: "kskcur", "kskpub", "kskrev", "kskobs", "zskcur", "zskpub", "zsknew", or "zskobs".

It returns 1 if the call is successful; 0 if it is not.

keyrec_signset_prefix(zone_name)

keyrec_signset_prefix() returns the signing set prefix formed by concatenating the zone name and $DEFSETPREFIX. This prefix should be followed by a numeric index.

keyrec_signset_addkey(signing_set_name,key_list)

keyrec_signset_addkey() adds the keys listed in key_list to the signing set named by signing_set_name. key_list may either be an array, or a set, or arguments to the routine. The keyrec is created if it does not already exist. It returns 1 if the call is successful; 0 if it is not.

keyrec_signset_delkey(signing_set_name,key_name)

keyrec_signset_delkey() deletes the key given in key_name from the signing set named by signing_set_name. It returns 1 if the call is successful; 0 if it is not.

keyrec_signset_haskey(signing_set_name,key_name)

keyrec_signset_haskey() returns a flag indicating if the key specified in key_name is one of the keys in the signing set named by signing_set_name. It returns 1 if the signing set has the key; 0 if it does not.

keyrec_signset_clear(keyrec_name)

keyrec_signset_clear() clears the entire signing set from the keyrec named by keyrec_name. It returns 1 if the call is successful; 0 if it is not.

keyrec_signsets()

keyrec_signsets() returns the names of the signing sets in the keyrec file. These names are returned in an array.

keyrec_signset_keys(keyrec_name,signset_type)

keyrec_signset_keys() returns the names of the keys that are members of a given signing set in the keyrec file. The keys are returned in a space-separated string.

There are two ways of calling keyrec_signset_keys(). The first method specifies a zone keyrec name and a signing set type. The signing set name is found by referencing the set field in the zone keyrec, then the keys field of that signing set is returned.

The second method specifies the signing set directly, and its keys field is returned.

Valid signing set types are:

kskcur        kskpub        kskrev        kskobs
zskcur        zskpub        zsknew        zskobs

The following errors are recognized, resulting in an undefined return:

  • keyrec_name is not a defined keyrec
  • signset_type is an invalid signing set type
  • the signing set keyrec is not a set keyrec

🛠️ KEYREC INTERNAL INTERFACES 🛠️

The interfaces in this section are intended for internal use by the keyrec.pm module. However, there are situations where external entities may have need of them.

⚠️ Use with caution, as misuse may result in damaged or lost keyrec files. Fr fr, be careful.

keyrec_init()

This routine initializes the internal keyrec data. Pending changes will be lost. An open keyrec file handle will remain open, though the data are no longer held internally. A new keyrec file must be read in order to use the keyrec.pm interfaces again.

keyrec_newkeyrec(kr_name,kr_type)

This interface creates a new keyrec. The keyrec_name and keyrec_hash fields in the keyrec are set to the values of the kr_name and kr_type parameters. kr_type must be either "key" or "zone".

Return values are:

  • 0 if the creation succeeded
  • -1 if an invalid keyrec type was given

🐞 KEYREC DEBUGGING INTERFACES 🐞

The following interfaces display information about the currently parsed keyrec file. They are intended to be used for debugging and testing, but may be useful at other times.

keyrec_dump_hash()

This routine prints the keyrec file as it is stored internally in a hash table. The keyrecs are printed in alphabetical order, with the fields alphabetized for each keyrec. New keyrecs and keyrec fields are alphabetized along with current keyrecs and fields. Comments from the keyrec file are not included with the hash table.

keyrec_dump_array()

This routine prints the keyrec file as it is stored internally in an array. The keyrecs are printed in the order given in the file, with the fields ordered in the same manner. New keyrecs are appended to the end of the array. keyrec fields added to existing keyrecs are added at the beginning of the keyrec entry. Comments and vertical whitespace are preserved as given in the keyrec file.

Copyright 2005-2014 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details.

👑 AUTHOR 👑

Wayne Morrison, tewok@tislabs.com

🌈 SEE ALSO 🌈

  • Net::DNS::SEC::Tools::conf(5)
  • Net::DNS::SEC::Tools::keyrec(5)

Okay that’s the whole keyrec(3) page, bestie 💖 it’s from perl v5.44.0, dated 2026-10-17. Bye! 🫶

📦 where this page comes from