#
# Copyright 2004-2014 SPARTA, Inc.  All rights reserved.  See the COPYING
# file distributed with this software for details
#
# DNSSEC Tools
#
#	Keyrec file format.
#

1;

#############################################################################

=pod

=head1 NAME

B<keyrec> - Zone and key data used by DNSSEC-Tools programs.

=head1 DESCRIPTION

I<keyrec> files contain data about zones signed by and keys generated by the
DNSSEC-Tools programs.  A I<keyrec> file is organized in sets of I<keyrec>
records.  Each I<keyrec> must be either of I<zone> type, I<set> type, or
I<key> type.
Zone I<keyrec>s describe how the zones were signed.
Set I<keyrec>s describe sets of key I<keyrec>s.
Key I<keyrec>s describe how encryption keys were generated.
A I<keyrec> consists of a set of keyword/value entries.

The DNSSEC-Tools B<keyrec.pm> module manipulates the contents of a I<keyrec>
file.  Module interfaces exist for looking up I<keyrec> records, creating
new records, and modifying existing records.

Comment lines and blank lines are ignored by the DNSSEC-Tools programs.
Comment lines start with either a '#' character or a ';' character.

A I<keyrec>'s name may consist of alphabetic characters, numbers, and several
special characters.  The special characters are the minus sign, the plus
sign, the underscore, the comma, the period, and the colon.

The values in a I<keyrec>'s entries may consist of alphabetic characters,
numbers, and several special characters.  The special characters are the minus
sign, the plus sign, the underscore, the comma, the period, the colon, the
forward-slash, the space, and the tab.

The B<keymod> command modifies the key parameters for a zone.  The
modifications will take effect in future invocations of B<zonesigner>, but
current and past keys will not be affected.  To make these changes, B<keymod>
places new entries in the zone I<keyrec>.  These entries are all temporary,
and are automatically removed once B<zonesigner> starts using the new
parameter values.  These temporary entries all begin with "new_" and the rest
of the entry keyword is a normal entry keyword.  For example, if B<keymod> is
used to modify the "ksklength" parameter, then a new entry will be added that
has the keyword "new_ksklength".  See B<keymod(8)> for more information.

=head1 FIELDS

The fields in a I<keyrec> record are described in this section.  The fields
in each type of record (zone, set, key) are described in their own subsection.

=head2 Zone Keyrec Fields

 * archivedir

The name of the key archive directory for this zone.

 * dsdir

The name of the directory to hold the zone's dsset files.

 * endtime

The time when the zone's SIG records expire.  This field is passed to
B<dnssec-signzone> as the argument to the I<-e> option.

 * gends

Boolean value to indicate whether or not DS records should be generated for
the zone.

 * keyrec_signdate

The textual timestamp of the zone I<keyrec>'s last update.
This is a translation of the I<keyrec_signsecs> field.

 * keyrec_signsecs

The numeric timestamp of the zone I<keyrec>'s last update.
This is measured in seconds since the epoch.

 * ksdir

The name of the directory to hold the zone's keyset files.

 * kskcount

The number of KSKs to generate for the zone.

 * kskcur

The name of the zone's Current KSK signing set.
This is used as the name of the signing set of KSK keys I<keyrec> fields.

 * kskpub

The name of the zone's Published KSK signing set.

 * kskdirectory

The directory that holds the KSK keys.

 * lastcmd

The most recent B<zonesigner> command line used for this zone.

 * lastset

The most recently generated signing set for the zone.

 * rollmgr

The name of the rollover manager for this zone.  This doubles as an indicator
that the zone actually is in rollover management.

 * serial

The most recent serial number for the zone.

 * signedzone

The name of the signed zone file for this zone.

 * szopts

Optional arguments passed to the B<dnssec-signzone> command.

 * zonefile

The name of the zone file for this zone.

 * zskcount

The number of ZSKs to generate for the zone.

 * zskcur

The name of the signing set for the current ZSK keys.
This is the name of the signing set's set I<keyrec>.

 * zskdirectory

The directory that holds the ZSK keys.

 * zskpub

The name of the signing set for the current ZSK keys.
This is the name of the signing set's set I<keyrec>.

 * zsknew

The name of the signing set for the current ZSK keys.
This is the name of the signing set's set I<keyrec>.

=head2 Set Keyrec Fields

 * keys

The list of keys in this signing set.  Each key listed should have a
corresponding key I<keyrec> whose name matches the key name.

 * keyrec_setdate

The textual timestamp of the signing set's last modification.
This is a translation of the I<keyrec_setsecs> field.

 * keyrec_setsecs

The numeric timestamp of the signing set's last modification.
This is measured in seconds since the epoch.

 * zonename

The name of the zone for which this signing set was generated.

=head2 Key Keyrec Fields

 * algorithm

The encryption algorithm used to generate this key.

 * keypath

The path to the key.  This may be an absolute or relative path, but it should
be one which B<zonesigner> may use (in conjunction with other I<keyrec>
fields to find the key.

 * keyrec_gendate

The textual timestamp of the key's creation.  This is a translation of
the I<keyrec_gensecs> field.

 * keyrec_gensecs

The numeric timestamp of the key's creation.  This is measured in seconds
since the epoch.

 * kgopts

Additional options to pass to the B<dnssec-keygen> command.

 * ksklength

The length of a KSK key.  This is only included in I<keyrec>s for KSK keys.

 * ksklife

The life of a KSK key.  This is only included in I<keyrec>s for KSK keys.

 * revperiod

The revocation period of a KSK key.  This is only included in
I<keyrec>s for KSK keys.

 * random

The random number generator used to generate this key.

 * zonename

The name of the zone for which this key was generated.

 * zsklength

The length of a ZSK key.  This is only included in I<keyrec>s for ZSK keys.

 * zsklife

The life of a ZSK key.  This is only included in I<keyrec>s for ZSK keys.

=head2 General Keyrec Fields

 * keyrec_type

The type of the I<keyrec>.

For zone I<keyrec>s, the value of this field will be "zone".

For set I<keyrec>s, the value of this field will be
"kskcur", "kskpub", "kskrev", "kskobs",
"zskcur", "zskpub", "zsknew", or "zskobs".

For key I<keyrec>s, the value of this field will be
"kskcur", "kskpub", "kskrev", "kskobs",
"zskcur", "zskpub", "zsknew", or "zskobs".

=head1 EXAMPLES

The following is an example of a zone I<keyrec>:

    zone        "example.com"
            zonefile        "db.example.com"
            signedzone      "db.example.com.signed"
            endtime         "+604800"
            archivedir      "/usr/etc/dnssec-tools/key-vault"
            kskcur          "signing-set-41"
            kskdirectory    "keydir"
            zskcur          "signing-set-42"
            zskpub          "signing-set-43"
            zsknew          "signing-set-44"
            lastset         "signing-set-44"
            keyrec_type     "zone"
            keyrec_signsecs "1123771721"
            keyrec_signdate "Thu Aug 11 14:48:41 2005"

The following is an example of a set I<keyrec>:

    set        "signing-set-42"
            zonename        "example.com"
            keys            "Kexample.com.+005+88888"
            keyrec_type     "zskcur"
            keyrec_setsecs  "1123771350"
            keyrec_setdate  "Thu Aug 11 14:42:30 2005"

The following is an example of a key I<keyrec>:

    key        "Kexample.com.+005+88888"
            zonename        "example.com"
            keyrec_type     "zskcur"
            algorithm       "rsasha1"
            random          "/dev/urandom"
            keypath         "./Kexample.com.+005+88888.key"
            ksklength       "2048"
            keyrec_gensecs  "1123771354"
            keyrec_gendate  "Thu Aug 11 14:42:34 2005"

=head1 COPYRIGHT

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

=head1 AUTHOR

Wayne Morrison, tewok@tislabs.com

=head1 SEE ALSO

B<lskrf(1)>

B<dnssec-signzone(8)>,
B<keyarch(8)>,
B<keymod(8)>,
B<signset-editor(8)>,
B<zonesigner(8)>

B<Net::DNS::SEC::Tools::keyrec(3)>

=cut
