Provided by: dnssec-tools_1.11-1_all bug

NAME

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

SYNOPSIS

         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();

         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();

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.

       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 must be to create a new keyrec file or open and read
       an existing one.  The keyrec_creat() interface creates a keyrec file if it does not exist.
       The keyrec_read() interface 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.) The keyrec_filestat() interface may be used check that the given file may be a
       keyrec file, though it doesn't check the file's contents.

       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.

       If the keyrec file has been modified, it must be explicitly written or the changes are not
       saved.  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.

KEYREC INTERFACES

       The interfaces to the Net::DNS::SEC::Tools::keyrec module are given below.

       keyrec_add(keyrec_type,keyrec_name,fields)
           This routine adds a new keyrec to the keyrec file and the internal representation of
           the file contents.  The keyrec is added to both the %keyrecs hash table and the
           @keyreclines array.

           keyrec_type specifies the type of the keyrec -- "key" or "zone".  keyrec_name is the
           name of the keyrec.  fields is a reference to a hash table that contains the
           name/value keyrec fields.  The keys of the hash table are always converted to
           lowercase, but the entry values are left as given.

           The ksklength entry is only added if the value of the keyrec_type field is "kskcur".

           The zsklength entry is only added if the value of the keyrec_type field is "zsk",
           "zskcur", "zskpub", or "zsknew".

           Timestamp fields are added 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.

           If a specified field isn't defined for the keyrec type, the entry isn't added.  This
           prevents zone keyrec data from getting mingled with key keyrec data.

           A blank line is added after the final line of the new keyrec.  After adding all new
           keyrec entries, the keyrec file is written but is not closed.

           Return values are:

               0 success
               -1 invalid I<krtype>

       keyrec_close()
           This interface saves the internal version of the keyrec file (opened with
           keyrec_read()) and closes the file handle.

       keyrec_creat(keyrec_file)
           This interface creates a keyrec file if it does not exist, and truncates the file if
           it already exists.

           keyrec_creat() returns 1 if the file was created successfully.  It returns 0 if there
           was an error in creating the file.

       keyrec_curkrf()
           This routine returns the name of the keyrec file that is currently in use.  This value
           is the filename passed to keyrec_read() or keyrec_creat(); it is not guaranteed to be
           either an absolute or relative filename.

       keyrec_defkrf()
           This routine returns the default keyrec filename from the DNSSEC-Tools configuration
           file.

       keyrec_del(keyrec_name)
           This routine deletes a keyrec from the keyrec file and the internal representation of
           the file contents.  The keyrec is deleted from both the %keyrecs hash table and the
           @keyreclines array.

           Only the keyrec itself is deleted from the file.  Any associated comments and blank
           lines surrounding it are left intact.

           Return values are:

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

       keyrec_delval(keyrec_name, field)
           This routine deletes the field from the keyrec named by keyrec_name.  The keyrec is
           deleted from both the %keyrecs hash table and the @keyreclines array.

           Return values are:

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

       keyrec_discard()
           This routine removes a keyrec file from use by a program.  The internally stored data
           are deleted and the keyrec file handle is closed.  However, modified data are not
           saved prior to closing the file handle.  Thus, modified and new data will be lost.

       keyrec_exists(keyrec_name)
           keyrec_exists() returns a boolean indicating if a keyrec exists that has the specified
           keyrec_name.

       keyrec_filestat(keyrec_name)
           keyrec_filestat() checks that a given file might be a reasonable candidate for a
           DNSSEC-Tools keyrec file.  The checks to be performed may be gleaned from the list of
           return values.

           Return values are:
               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)
           keyrec_fullrec() returns a reference to the keyrec specified in keyrec_name.

       keyrec_keyfields()
           This routine returns a list of the recognized fields for a key keyrec.

       keyrec_keypaths(zonename,keytype)
           keyrec_keypaths() returns a list of paths to a set of key files for a given zone.  The
           zone is specified in zonename and the type of key is given in keytype.

           keytype must be one of the following:  "kskcur", "kskpub", "kskrev", "kskobs"",
           "zskcur", "zskpub", "zsknew", "zskobs", "ksk", "zsk", or "all".  Case does not matter
           for the keytype.

           If keytype is one of the special labels ("ksk", "zsk", or "all") then a set of key
           paths will be returned.  A keytype of "ksk" will return paths to all KSK keys for the
           zone, a keytype of "zsk" will return paths to all ZSK keys for the zone, and a keytype
           of "all" will return paths to all keys for the zone,

           If the given key type is not defined in the given zone's zone keyrec or if the key
           type is not recognized, then a null set is returned.

       keyrec_names()
           This routine returns a list of the keyrec names from the file.

       keyrec_open(keyrec_file) DEPRECATED
           This routine used to open an existing DNSSEC-Tools keyrec file.  However, this was an
           unnecessary operation since keyrec_read() would open the file if it wasn't already
           open.

           This call will eventually be removed.  For now, it calls keyrec_filestat() to check
           the validity of the specified keyrec file.

           Return values:

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

           For backwards compatibility, the success/failure meaning of the return values matches
           the success/failure meaning of keyrec_open()'s original returns.

       keyrec_read(keyrec_file)
           This interface reads the specified keyrec file and parses it into a keyrec hash table
           and a file contents array.  keyrec_read() must be called prior to any of the other
           Net::DNS::SEC::Tools::keyrec calls.  If another keyrec is already open, then it is
           saved and closed prior to opening the new keyrec.

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

           Failure return values:

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

       keyrec_recval(keyrec_name,keyrec_field)
           This routine returns the value of a specified field in a given keyrec.  keyrec_name is
           the name of the particular keyrec to consult.  keyrec_field is the field name within
           that keyrec.

           For example, the current keyrec file contains the following keyrec:

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

           The call:

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

           will return the value "db.example.com".

       keyrec_revoke_check(key)
           This interface checks a revoked KSK's keyrec to determine if it is 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
           this is greater than the revocation period, the 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 I<keyrec> data)

       keyrec_saveas(keyrec_file_copy)
           This interface 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 is closed, but the original file and the file handle to the original file
           are not affected.

       keyrec_setval(keyrec_type,keyrec_name,field,value)
           Set the value of a name/field pair in a specified keyrec.  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.

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

           Return values are:

               0 if the creation succeeded
               -1 invalid type was given

       keyrec_settime(keyrec_type,keyrec_name)
           Set the timestamp of a specified keyrec.  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.  The keyrec's keyrec_signdate and keyrec_signsecs fields are modified.

       keyrec_write()
           This interface saves the internal version of the keyrec file (opened with or
           keyrec_read()).  It does not close the file handle.  As an efficiency measure, an
           internal modification flag is checked prior to writing the file.  If the program has
           not modified the contents of the keyrec file, it is not rewritten.

           keyrec_write() gets an exclusive lock on the keyrec file while writing.

       keyrec_zonefields()
           This routine returns a list of the recognized fields for a zone keyrec.

KEYREC SIGNING-SET INTERFACES

       Signing sets are collections of encryption keys, defined by inclusion in a particular
       "set" keyrec.  The names of the keys are in the keyrec's keys record, which contains the
       names of the key keyrecs.  Due to the way key names are handled, the names in a signing
       set must not contain spaces.

       The signing-set-specific interfaces are given below.

       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.  It is given the type type, which must be one of the following:  "kskcur",
           "kskpub", "kskrev", "kskobs", "zskcur", "zskpub", "zsknew", or "zskobs".

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

       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 to 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 described 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.

       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 I<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

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

AUTHOR

       Wayne Morrison, tewok@users.sourceforge.net

SEE ALSO

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