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();
$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();
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_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 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-2012 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)
