NAME

maintkeydb - Command line interface to a database containing DNSSEC keys.

SYNOPSIS

        maintkeydb -h
	maintkeydb [-v verbose] [-c configfile] [-i] <commands> <arguments>

The -i switch turns on interactive mode, which is supposed to be more verbose and guide you through the process (more or less current functionality).

With the -h switch a short help is returned.

DESCRIPTION

the interface defines a number of commands:

	create
	delete_name
	delete_id
	list
	rollover
	showkeys
	parentdata
        state

In the interactive mode there are additional commands like "help" and "exit".

The tool is designed with the procedures as documented in [1] in mind.

The basic commands take their own argument, see below.

COMMANDS

Note, in the argument descriptions is a shortcut for <"RSASHA1"|"RSAMD5"|"RSA"|"DSA">

create

 maintkeydb create ["force"]  <"ksk"|"zsk"|"both"> <algorithm> <size> \
	<zone[[ zone],...]>

Create a KSK or ZSK file of given algorithm and size for the specified zones.

If no ZSK exists for a given zone the create function will create two keys, one marked as "active" (i.e. used for "signing"). This allows for the rollover scheme as designed in [1].

If for the given zone and type a key marked as "active" exists the create function will not mark newly created keys as "active".

If "default" is provided as the argument for size than the default sizes from the dnssecmain.conf file are used.

To prevent mistakes that will cause the rollover commands to fail the create method will not create a second KSK or a third ZSK unless the "force" argument is specified.

Return values:

 returns 0 and prints the name of the created key to STDOUT 
 on success

 returns a nonzero vallue and potentionally prints warnings 
 to STDERR.

delete

has two forms:

 maintkeydb delete_id  <zone> <algorithm> <keyID[[ keyID] ...]> 

deletes one or more keys from the specified zone, the keys are identified by the keyID.

 maintkeydb delete_name  <"ksk"|"zsk"|"both">  <algorithm> <zone[[ zone],...]> 

deletes all zsk or all ksk for the given zones. (Be careful with this command, it is very destructive).

Return values:

 returns 0 and prints information  about the deleted keys to STDOUT on
 success

 returns a nonzero value and potentially prints warnings to STDERR on
 error

state

 maintkeydb state  <zone> <algorithm> <keyID[[ keyID] ...]> 

states the active/inactive state of the keys specified by the given keyIDs.

Usage of the state command may cause the database to be altered in such a way that the premises for the rollover commands are not met.

Return values:

 returns 0 on success

 returns a nonzero value and potentially prints warnings to STDERR on
 error

list

  maintkeydb list ["active"|"inactive"|"published"|"rolled"] 
  ["ksk"|"zsk"|"both"] [zone[[ zone],...]]

Lists keys in the database.

Withouth any arguments all keys in the database are returned.

 The output can be filtered to show only active, inactive, published
 or keys that are being rolled.
   

 when one or more zones are specified it only lists the keys for
 those zones.

 when "ksk" or "zsk" is specified only the ksk or zsk keys are
 listed.

Return values:

returns 0 and prints a formated list to STDOUT if keys are found that match the search criterea. The format of the output is a tab seperated list of the following fields name, algorithm, keyid, KSK or ZSK, active or inactive such as:.

 example.com DSA 39372 ZSK active
 example.com RSASHA1 12672 ZSK inactive

returns 1 if no keys are found that match the search criterea

returns a value >1 if an error occurs and potentially prints warnings to STDERR on error

rollover

  mainkeydb rollover <"ksk-stage1"|"ksk-stage1"|"zsk-stage1"|"zsk-stage2"> \
   <algorithm>  <zone[[ zone]...]>

rollovers the zsk or ksk for the specified zones.

The rollover only works in specific circumstances. The premises are tested and if they are not sattisfied for _any_ of the specified zone an error will be printed to STDERR and no rollover will be done for any of the specified zones.

The premises under which rollover succeeds should be obeyed if the user has never used the "create" command with the "force" argument and has never issued "state" or "deleted" for the given zone.

Return values:

 returns 0 on success

 returns a nonzero value and potentially prints warnings to STDERR on
 error

This is an implementation of the "Pre-publish keyset rollover" as documented in [1].

For the rollover of a ZSK the premises is that there is one active and one inactive ZSK. During the rollover the inactive ZSK is made active, the active ZSK is deleted and a new inactive ZSK is created.

This is an implementation of the a double signature scheme keyrollover as documented for KSK rollovers in [1].

The premises for the ksk-stage1 rollover is that there is are one or more active KSK and only one published KSK. The rollover will mark the oldest active KSK as being in "rollover" and make the published keys as active.

The premises of the ksk-stage2 rollover is that there are two or more active KSKs one of wich, the oldest, is marked as being in rollover. During the ksk-stage2 rollover the key marked as being in rollover state will be removed and a new active KSK will be added.

The system does not check for the availability of DS RRs at the parent.

This is what a user would do during a key rollover

Confirm that there is no key currently in rollover state. bash> maintkeydb list rollover example.com (this command returns nothing if there are no keys being rolled)

Nor rollover start the rollover of the KSK key. bash> maintkeydb rollover ksk-stage1 example.com

List the key material and the DS record that needs to be send to the parent.

  bash> maintkeydb showkeys ds example.com
  bash> 
  example.com IN KEY 256 3 5 ( AB12cD...
    ...
  example.com IN DS 1 ab123...  

After the zone is signed with the signing tool that uses the database. And after the zone is published in the DNS the key shown will need to be uploaded to the parent. The user will have to wait untill the DS RR shown is served by the parents server, in this particular example the com zone. Then the user can proceed with:

  bash> maintkeydb list rollover all
  example.com         	RSASHA1	27393	KSK active     (47d04h23m)	(R)

  bash> maintkeydb rollover ksk-stage2 example.com

Now resign and publish the zone in the DNS.

showkeys

   maintkeydb showkey ["ds"] [zone[[ zone],...]]

This command will show the DNSKEY RR set as it will appear in the zone.

If "ds" is specified than only the keysigning keys is printed and in addition the DS RRs which match these.

Note that this command will print all the keysingin keys. If you want to get the data that needs to be forwarded to the parent use the parentdata command instead.

Note that the TTL of these records is set to 0.

Return values:

 returns 0 on success and prints the result to STDOUT

 returns a nonzero value and potentially prints warnings to STDERR on
 error

parentdata

   maintkeydb parentdata <"ds"|"key"|"both"> [zone[[ zone],...]]

Prints the data that will need to be sent to the parent for the zones specified.

The first argument specifies if the DNSKEY RRs, the DS RRs or both need to be printed for each zone.

The output is sorted per zone.

LOGGING

Logging needs improvement, suggestions are welcomed.

Logging is provided through the LOG::Log4perl interface. The logging configuration is read from /usr/local/etc/log4perl.conf, /etc/log4perl.conf or set to the default

    log4perl.rootLogger=FATAL,Screen
    log4perl.appender.Logfile          = Log::Log4perl::Appender::File
    log4perl.appender.Logfile.filename = test.log
    log4perl.appender.Logfile.layout   = Log::Log4perl::Layout::PatternLayout
    log4perl.appender.Logfile.layout.ConversionPattern = [%r] %F %L %m%n

    log4perl.appender.Screen         = Log::Log4perl::Appender::Screen
    log4perl.appender.Screen.stderr  = 0
    log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout

Please consult LOG::Log4perl for assistance.

TODO, FEATURES, BUGS.

Zone names that have names that equal arguments in the funtion above such as "ksk", "inactive" may cause parsing problems.

Add a "checkksk" command that will verify if the proper DS is available for a KSK at the parent.

The error messages may be a little pedantic at times.

There is an error saying "You will need to hack the database". We will need recovery procedures written.

REFERENCES

[1] Kolkman and Gieben, "DNSSEC Operational Practices", draft-ietf-dnsop-dnssec-operational-practices-01.txt (work in progress).

COPYRIGHT

COPYRIGHT

Copyright (c) 2004 RIPE NCC. Author Olaf M. Kolkman

All Rights Reserved

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of the author not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS; IN NO EVENT SHALL AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.