.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "keyrec 3" .TH keyrec 3 2023-07-29 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Net::DNS::SEC::Tools::keyrec \- DNSSEC\-Tools keyrec file operations .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& 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",\e%zone_krfields); \& keyrec_add("key","Kexample.com.+005+12345",\e%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(); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" The \fBNet::DNS::SEC::Tools::keyrec\fR module manipulates the contents of a DNSSEC-Tools \fIkeyrec\fR file. \fIkeyrec\fR files contain data about zones signed by and keys generated by the DNSSEC-Tools programs. Module interfaces exist for looking up \fIkeyrec\fR records, creating new records, and modifying existing records. .PP A \fIkeyrec\fR file is organized in sets of \fIkeyrec\fR records. Each \fIkeyrec\fR must be either of \fIkey\fR type or \fIzone\fR type. Key \fIkeyrec\fRs describe how encryption keys were generated, zone \fIkeyrec\fRs describe how zones were signed. A \fIkeyrec\fR consists of a set of keyword/value entries. The following is an example of a key \fIkeyrec\fR: .PP .Vb 11 \& 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" .Ve .PP The first step in using this module \fBmust\fR be to create a new \fIkeyrec\fR file or open and read an existing one. The \fR\f(BIkeyrec_creat()\fR\fI\fR interface creates a \&\fIkeyrec\fR file if it does not exist. The \fI\fR\f(BIkeyrec_read()\fR\fI\fR 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 \&\fBNet::DNS::SEC::Tools::keyrec\fR routines) and in an array (for preserving formatting and comments.) The \fI\fR\f(BIkeyrec_filestat()\fR\fI\fR interface may be used check that the given file may be a \fIkeyrec\fR file, though it doesn't check the file's contents. .PP After the file has been read, the contents are referenced using \&\fR\f(BIkeyrec_fullrec()\fR\fI\fR and \fI\fR\f(BIkeyrec_recval()\fR\fI\fR. The \fIkeyrec\fR contents are modified using \fI\fR\f(BIkeyrec_add()\fR\fI\fR, and \fI\fR\f(BIkeyrec_setval()\fR\fI\fR. \fI\fR\f(BIkeyrec_settime()\fR\fI\fR will update a \fIkeyrec\fR's timestamp to the current time. \fIkeyrec\fRs may be deleted with the \fI\fR\f(BIkeyrec_del()\fR\fI\fR interface. .PP If the \fIkeyrec\fR file has been modified, it must be explicitly written or the changes are not saved. \fR\f(BIkeyrec_write()\fR\fI\fR saves the new contents to disk. \&\fI\fR\f(BIkeyrec_saveas()\fR\fI\fR saves the in-memory \fIkeyrec\fR contents to the specified file name, without affecting the original file. .PP \&\fR\f(BIkeyrec_close()\fR\fI\fR saves the file and close the Perl file handle to the \&\fIkeyrec\fR file. If a \fIkeyrec\fR file is no longer wanted to be open, yet the contents should not be saved, \fI\fR\f(BIkeyrec_discard()\fR\fI\fR gets rid of the data, and closes the file handle \fBwithout\fR saving any modified data. .SH "KEYREC INTERFACES" .IX Header "KEYREC INTERFACES" The interfaces to the \fBNet::DNS::SEC::Tools::keyrec\fR module are given below. .IP \fIkeyrec_add(keyrec_type,keyrec_name,fields)\fR 4 .IX Item "keyrec_add(keyrec_type,keyrec_name,fields)" This routine adds a new \fIkeyrec\fR to the \fIkeyrec\fR file and the internal representation of the file contents. The \fIkeyrec\fR is added to both the \&\fR\f(CI%keyrecs\fR\fI\fR hash table and the \fI\fR\f(CI@keyreclines\fR\fI\fR array. .Sp \&\fIkeyrec_type\fR specifies the type of the \fIkeyrec\fR \-\- "key" or "zone". \&\fIkeyrec_name\fR is the name of the \fIkeyrec\fR. \fIfields\fR is a reference to a hash table that contains the name/value \fIkeyrec\fR fields. The keys of the hash table are always converted to lowercase, but the entry values are left as given. .Sp The \fIksklength\fR entry is only added if the value of the \fIkeyrec_type\fR field is "kskcur". .Sp The \fIzsklength\fR entry is only added if the value of the \fIkeyrec_type\fR field is "zsk", "zskcur", "zskpub", or "zsknew". .Sp Timestamp fields are added at the end of the \fIkeyrec\fR. For key \fIkeyrec\fRs, the \fIkeyrec_gensecs\fR and \fIkeyrec_gendate\fR timestamp fields are added. For zone \fIkeyrec\fRs, the \fIkeyrec_signsecs\fR and \fIkeyrec_signdate\fR timestamp fields are added. .Sp If a specified field isn't defined for the \fIkeyrec\fR type, the entry isn't added. This prevents zone \fIkeyrec\fR data from getting mingled with key \&\fIkeyrec\fR data. .Sp A blank line is added after the final line of the new \fIkeyrec\fR. After adding all new \fIkeyrec\fR entries, the \fIkeyrec\fR file is written but is not closed. .Sp Return values are: .Sp .Vb 2 \& 0 success \& \-1 invalid I .Ve .IP \fR\f(BIkeyrec_close()\fR\fI\fR 4 .IX Item "keyrec_close()" This interface saves the internal version of the \fIkeyrec\fR file (opened with \&\fR\f(BIkeyrec_read()\fR\fI\fR) and closes the file handle. .IP \fIkeyrec_creat(keyrec_file)\fR 4 .IX Item "keyrec_creat(keyrec_file)" This interface creates a \fIkeyrec\fR file if it does not exist, and truncates the file if it already exists. .Sp \&\fR\f(BIkeyrec_creat()\fR\fI\fR returns 1 if the file was created successfully. It returns 0 if there was an error in creating the file. .IP \fR\f(BIkeyrec_curkrf()\fR\fI\fR 4 .IX Item "keyrec_curkrf()" This routine returns the name of the \fIkeyrec\fR file that is currently in use. This value is the filename passed to \fR\f(BIkeyrec_read()\fR\fI\fR or \fI\fR\f(BIkeyrec_creat()\fR\fI\fR; it is not guaranteed to be either an absolute or relative filename. .IP \fR\f(BIkeyrec_defkrf()\fR\fI\fR 4 .IX Item "keyrec_defkrf()" This routine returns the default \fIkeyrec\fR filename from the DNSSEC-Tools configuration file. .IP \fIkeyrec_del(keyrec_name)\fR 4 .IX Item "keyrec_del(keyrec_name)" This routine deletes a \fIkeyrec\fR from the \fIkeyrec\fR file and the internal representation of the file contents. The \fIkeyrec\fR is deleted from both the \fR\f(CI%keyrecs\fR\fI\fR hash table and the \fI\fR\f(CI@keyreclines\fR\fI\fR array. .Sp Only the \fIkeyrec\fR itself is deleted from the file. Any associated comments and blank lines surrounding it are left intact. .Sp Return values are: .Sp .Vb 2 \& 0 successful keyrec deletion \& \-1 invalid krtype (empty string or unknown name) .Ve .IP "\fIkeyrec_delval(keyrec_name, field)\fR" 4 .IX Item "keyrec_delval(keyrec_name, field)" This routine deletes the \fIfield\fR from the \fIkeyrec\fR named by \fIkeyrec_name\fR. The \fIkeyrec\fR is deleted from both the \fR\f(CI%keyrecs\fR\fI\fR hash table and the \&\fI\fR\f(CI@keyreclines\fR\fI\fR array. .Sp Return values are: .Sp .Vb 3 \& \-1 keyrec_name not the name of an existing keyrec \& 0 field not found in keyrec \& 1 field deleted from keyrec .Ve .IP \fR\f(BIkeyrec_discard()\fR\fI\fR 4 .IX Item "keyrec_discard()" This routine removes a \fIkeyrec\fR file from use by a program. The internally stored data are deleted and the \fIkeyrec\fR file handle is closed. However, modified data are not saved prior to closing the file handle. Thus, modified and new data will be lost. .IP \fIkeyrec_exists(keyrec_name)\fR 4 .IX Item "keyrec_exists(keyrec_name)" \&\fR\f(BIkeyrec_exists()\fR\fI\fR returns a boolean indicating if a \fIkeyrec\fR exists that has the specified \fIkeyrec_name\fR. .IP \fIkeyrec_filestat(keyrec_name)\fR 4 .IX Item "keyrec_filestat(keyrec_name)" \&\fR\f(BIkeyrec_filestat()\fR\fI\fR checks that a given file might be a reasonable candidate for a DNSSEC-Tools \fIkeyrec\fR file. The checks to be performed may be gleaned from the list of return values. .Sp 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 .IP \fIkeyrec_fullrec(keyrec_name)\fR 4 .IX Item "keyrec_fullrec(keyrec_name)" \&\fR\f(BIkeyrec_fullrec()\fR\fI\fR returns a reference to the \fIkeyrec\fR specified in \&\fIkeyrec_name\fR. .IP \fR\f(BIkeyrec_keyfields()\fR\fI\fR 4 .IX Item "keyrec_keyfields()" This routine returns a list of the recognized fields for a key \fIkeyrec\fR. .IP \fIkeyrec_keypaths(zonename,keytype)\fR 4 .IX Item "keyrec_keypaths(zonename,keytype)" \&\fR\f(BIkeyrec_keypaths()\fR\fI\fR returns a list of paths to a set of key files for a given zone. The zone is specified in \fIzonename\fR and the type of key is given in \fIkeytype\fR. .Sp \&\fIkeytype\fR must be one of the following: "kskcur", "kskpub", "kskrev", "kskobs"", "zskcur", "zskpub", "zsknew", "zskobs", "ksk", "zsk", or "all". Case does not matter for the \fIkeytype\fR. .Sp If \fIkeytype\fR is one of the special labels ("ksk", "zsk", or "all") then a set of key paths will be returned. A \fIkeytype\fR of "ksk" will return paths to all KSK keys for the zone, a \fIkeytype\fR of "zsk" will return paths to all ZSK keys for the zone, and a \fIkeytype\fR of "all" will return paths to all keys for the zone, .Sp If the given key type is not defined in the given zone's zone \fIkeyrec\fR or if the key type is not recognized, then a null set is returned. .IP \fR\f(BIkeyrec_names()\fR\fI\fR 4 .IX Item "keyrec_names()" This routine returns a list of the \fIkeyrec\fR names from the file. .IP "\fIkeyrec_open(keyrec_file)\fR \fBDEPRECATED\fR" 4 .IX Item "keyrec_open(keyrec_file) DEPRECATED" This routine used to open an existing DNSSEC-Tools \fIkeyrec\fR file. However, this was an unnecessary operation since \fR\f(BIkeyrec_read()\fR\fI\fR would open the file if it wasn't already open. .Sp This call will eventually be removed. For now, it calls \fR\f(BIkeyrec_filestat()\fR\fI\fR to check the validity of the specified \fIkeyrec\fR file. .Sp Return values: .Sp .Vb 2 \& 1 is the file passes all of keyrec_filestat()\*(Aqs tests \& 0 is the file fails any of keyrec_filestat()\*(Aqs tests .Ve .Sp For backwards compatibility, the success/failure meaning of the return values matches the success/failure meaning of \fR\f(BIkeyrec_open()\fR\fI\fR's original returns. .IP \fIkeyrec_read(keyrec_file)\fR 4 .IX Item "keyrec_read(keyrec_file)" This interface reads the specified \fIkeyrec\fR file and parses it into a \&\fIkeyrec\fR hash table and a file contents array. \fR\f(BIkeyrec_read()\fR\fI\fR \fBmust\fR be called prior to any of the other \fBNet::DNS::SEC::Tools::keyrec\fR calls. If another \fIkeyrec\fR is already open, then it is saved and closed prior to opening the new \fIkeyrec\fR. .Sp Upon success, \fR\f(BIkeyrec_read()\fR\fI\fR returns the number of \fIkeyrec\fRs read from the file. .Sp Failure return values: .Sp .Vb 3 \& \-1 specified I file doesn\*(Aqt exist \& \-2 unable to open I file \& \-3 duplicate I names in file .Ve .IP \fIkeyrec_recval(keyrec_name,keyrec_field)\fR 4 .IX Item "keyrec_recval(keyrec_name,keyrec_field)" This routine returns the value of a specified field in a given \fIkeyrec\fR. \&\fIkeyrec_name\fR is the name of the particular \fIkeyrec\fR to consult. \&\fIkeyrec_field\fR is the field name within that \fIkeyrec\fR. .Sp For example, the current \fIkeyrec\fR file contains the following \fIkeyrec\fR: .Sp .Vb 2 \& zone "example.com" \& zonefile "db.example.com" .Ve .Sp The call: .Sp .Vb 1 \& keyrec_recval("example.com","zonefile") .Ve .Sp will return the value "db.example.com". .IP \fIkeyrec_revoke_check(key)\fR 4 .IX Item "keyrec_revoke_check(key)" This interface checks a revoked KSK's \fIkeyrec\fR 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 \fIkeyrec\fR. .Sp 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. .Sp Return values: .Sp .Vb 5 \& 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 data) .Ve .IP \fIkeyrec_saveas(keyrec_file_copy)\fR 4 .IX Item "keyrec_saveas(keyrec_file_copy)" This interface saves the internal version of the \fIkeyrec\fR file (opened with or \fR\f(BIkeyrec_read()\fR\fI\fR) to the file named in the \fIkeyrec_file_copy\fR parameter. The new file's file handle is closed, but the original file and the file handle to the original file are not affected. .IP \fIkeyrec_setval(keyrec_type,keyrec_name,field,value)\fR 4 .IX Item "keyrec_setval(keyrec_type,keyrec_name,field,value)" Set the value of a \fIname/field\fR pair in a specified \fIkeyrec\fR. The file is \&\fBnot\fR written after updating the value. The value is saved in both \&\fR\f(CI%keyrecs\fR\fI\fR and in \fI\fR\f(CI@keyreclines\fR\fI\fR, and the file-modified flag is set. .Sp \&\fIkeyrec_type\fR specifies the type of the \fIkeyrec\fR. This is only used if a new \fIkeyrec\fR is being created by this call. \&\fIkeyrec_name\fR is the name of the \fIkeyrec\fR that will be modified. \&\fIfield\fR is the \fIkeyrec\fR field which will be modified. \&\fIvalue\fR is the new value for the field. .Sp Return values are: .Sp .Vb 2 \& 0 if the creation succeeded \& \-1 invalid type was given .Ve .IP \fIkeyrec_settime(keyrec_type,keyrec_name)\fR 4 .IX Item "keyrec_settime(keyrec_type,keyrec_name)" Set the timestamp of a specified \fIkeyrec\fR. The file is \fBnot\fR written after updating the value. The value is saved in both \fR\f(CI%keyrecs\fR\fI\fR and in \&\fI\fR\f(CI@keyreclines\fR\fI\fR, and the file-modified flag is set. The \fIkeyrec\fR's \&\fIkeyrec_signdate\fR and \fIkeyrec_signsecs\fR fields are modified. .IP \fR\f(BIkeyrec_write()\fR\fI\fR 4 .IX Item "keyrec_write()" This interface saves the internal version of the \fIkeyrec\fR file (opened with or \fR\f(BIkeyrec_read()\fR\fI\fR). 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 \fIkeyrec\fR file, it is not rewritten. .Sp \&\fR\f(BIkeyrec_write()\fR\fI\fR gets an exclusive lock on the \fIkeyrec\fR file while writing. .IP \fR\f(BIkeyrec_zonefields()\fR\fI\fR 4 .IX Item "keyrec_zonefields()" This routine returns a list of the recognized fields for a zone \fIkeyrec\fR. .SH "KEYREC SIGNING-SET INTERFACES" .IX Header "KEYREC SIGNING-SET INTERFACES" Signing sets are collections of encryption keys, defined by inclusion in a particular "set" \fIkeyrec\fR. The names of the keys are in the \fIkeyrec\fR's \&\fIkeys\fR record, which contains the names of the key \fIkeyrec\fRs. Due to the way key names are handled, the names in a signing set must not contain spaces. .PP The signing-set-specific interfaces are given below. .IP \fIkeyrec_signset_newname(zone_name)\fR 4 .IX Item "keyrec_signset_newname(zone_name)" \&\fR\f(BIkeyrec_signset_newname()\fR\fI\fR creates a name for a new signing set. The name will be generated by referencing the \fIlastset\fR field in the \fIkeyrec\fR for zone \fIzone_name\fR, if the \fIkeyrec\fR has such a field. The set index number (described below) will be incremented and the \fIlastset\fR with the new index number will be returned as the new signing set name. If the zone \fIkeyrec\fR does not have a \fIlastset\fR field, then the default set name of \&\fIsigning\-set\-0\fR will be used. .Sp The set index number is the first number found in the \fIlastset\fR 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: .Sp .Vb 7 \& lastset field index \& \-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\- \& signing\-set\-0 0 \& signing\-0\-set 0 \& 1\-signing\-0\-set 1 \& signing\-88\-set\-1 88 \& signingset4321 4321 .Ve .IP \fIkeyrec_signset_new(zone,signing_set_name,set_type)\fR 4 .IX Item "keyrec_signset_new(zone,signing_set_name,set_type)" \&\fR\f(BIkeyrec_signset_new()\fR\fI\fR creates the signing set named by \fIsigning_set_name\fR for the zone \fIzone\fR. It is given the type \fItype\fR, which must be one of the following: "kskcur", "kskpub", "kskrev", "kskobs", "zskcur", "zskpub", "zsknew", or "zskobs". .Sp It returns 1 if the call is successful; 0 if it is not. .IP \fIkeyrec_signset_prefix(zone_name)\fR 4 .IX Item "keyrec_signset_prefix(zone_name)" \&\fR\f(BIkeyrec_signset_prefix()\fR\fI\fR returns the signing set prefix formed by concatenating the zone name and \f(CW$DEFSETPREFIX\fR. This prefix should be followed by a numeric index. .IP \fIkeyrec_signset_addkey(signing_set_name,key_list)\fR 4 .IX Item "keyrec_signset_addkey(signing_set_name,key_list)" \&\fR\f(BIkeyrec_signset_addkey()\fR\fI\fR adds the keys listed in \fIkey_list\fR to the signing set named by \fIsigning_set_name\fR. \fIkey_list\fR may either be an array or a set or arguments to the routine. The \fIkeyrec\fR is created if it does not already exist. It returns 1 if the call is successful; 0 if it is not. .IP \fIkeyrec_signset_delkey(signing_set_name,key_name)\fR 4 .IX Item "keyrec_signset_delkey(signing_set_name,key_name)" \&\fR\f(BIkeyrec_signset_delkey()\fR\fI\fR deletes the key given in \fIkey_name\fR to the signing set named by \fIsigning_set_name\fR. It returns 1 if the call is successful; 0 if it is not. .IP \fIkeyrec_signset_haskey(signing_set_name,key_name)\fR 4 .IX Item "keyrec_signset_haskey(signing_set_name,key_name)" \&\fR\f(BIkeyrec_signset_haskey()\fR\fI\fR returns a flag indicating if the key specified in \fIkey_name\fR is one of the keys in the signing set named by \&\fIsigning_set_name\fR. It returns 1 if the signing set has the key; 0 if it does not. .IP \fIkeyrec_signset_clear(keyrec_name)\fR 4 .IX Item "keyrec_signset_clear(keyrec_name)" \&\fR\f(BIkeyrec_signset_clear()\fR\fI\fR clears the entire signing set from the \fIkeyrec\fR named by \fIkeyrec_name\fR. It returns 1 if the call is successful; 0 if it is not. .IP \fR\f(BIkeyrec_signsets()\fR\fI\fR 4 .IX Item "keyrec_signsets()" \&\fR\f(BIkeyrec_signsets()\fR\fI\fR returns the names of the signing sets in the \fIkeyrec\fR file. These names are returned in an array. .IP \fIkeyrec_signset_keys(keyrec_name,signset_type)\fR 4 .IX Item "keyrec_signset_keys(keyrec_name,signset_type)" \&\fR\f(BIkeyrec_signset_keys()\fR\fI\fR returns the names of the keys that are members of a given signing set in the \fIkeyrec\fR file. The keys are returned in a space-separated string. .Sp There are two ways of calling \fR\f(BIkeyrec_signset_keys()\fR\fI\fR. The first method specifies a zone \fIkeyrec\fR name and a signing set type. The signing set name is found by referencing the set field in the zone \fIkeyrec\fR, then the \fIkeys\fR field of that signing set is returned. .Sp The second method specifies the signing set directly, and its \fIkeys\fR field is returned. .Sp Valid signing set types are: .Sp .Vb 2 \& kskcur kskpub kskrev kskobs \& zskcur zskpub zsknew zskobs .Ve .Sp The following errors are recognized, resulting in an undefined return: .Sp .Vb 3 \& keyrec_name is not a defined keyrec \& signset_type is an invalid signing set type \& the signing set keyrec is not a set keyrec .Ve .SH "KEYREC INTERNAL INTERFACES" .IX Header "KEYREC INTERNAL INTERFACES" The interfaces described in this section are intended for internal use by the \&\fBkeyrec.pm\fR module. However, there are situations where external entities may have need of them. Use with caution, as misuse may result in damaged or lost \fIkeyrec\fR files. .IP \fR\f(BIkeyrec_init()\fR\fI\fR 4 .IX Item "keyrec_init()" This routine initializes the internal \fIkeyrec\fR data. Pending changes will be lost. An open \fIkeyrec\fR file handle will remain open, though the data are no longer held internally. A new \fIkeyrec\fR file must be read in order to use the \fBkeyrec.pm\fR interfaces again. .IP \fIkeyrec_newkeyrec(kr_name,kr_type)\fR 4 .IX Item "keyrec_newkeyrec(kr_name,kr_type)" This interface creates a new \fIkeyrec\fR. The \fIkeyrec_name\fR and \fIkeyrec_hash\fR fields in the \fIkeyrec\fR are set to the values of the \fIkr_name\fR and \fIkr_type\fR parameters. \fIkr_type\fR must be either "key" or "zone". .Sp Return values are: .Sp .Vb 2 \& 0 if the creation succeeded \& \-1 if an invalid I type was given .Ve .SH "KEYREC DEBUGGING INTERFACES" .IX Header "KEYREC DEBUGGING INTERFACES" The following interfaces display information about the currently parsed \&\fIkeyrec\fR file. They are intended to be used for debugging and testing, but may be useful at other times. .IP \fR\f(BIkeyrec_dump_hash()\fR\fI\fR 4 .IX Item "keyrec_dump_hash()" This routine prints the \fIkeyrec\fR file as it is stored internally in a hash table. The \fIkeyrec\fRs are printed in alphabetical order, with the fields alphabetized for each \fIkeyrec\fR. New \fIkeyrec\fRs and \fIkeyrec\fR fields are alphabetized along with current \fIkeyrec\fRs and fields. Comments from the \&\fIkeyrec\fR file are not included with the hash table. .IP \fR\f(BIkeyrec_dump_array()\fR\fI\fR 4 .IX Item "keyrec_dump_array()" This routine prints the \fIkeyrec\fR file as it is stored internally in an array. The \fIkeyrec\fRs are printed in the order given in the file, with the fields ordered in the same manner. New \fIkeyrec\fRs are appended to the end of the array. \fIkeyrec\fR fields added to existing \&\fIkeyrec\fRs are added at the beginning of the \fIkeyrec\fR entry. Comments and vertical whitespace are preserved as given in the \&\fIkeyrec\fR file. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2005\-2014 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details. .SH AUTHOR .IX Header "AUTHOR" Wayne Morrison, tewok@tislabs.com .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBNet::DNS::SEC::Tools::conf\|(5)\fR, \&\fBNet::DNS::SEC::Tools::keyrec\|(5)\fR