You're viewing an archived page. It is no longer being updated.
This content is only available for historical reference.
maintkeydb - Command line interface to a database containing DNSSEC keys.
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.
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.
Note, in the argument descriptions is a shortcut for <"RSASHA1"|"RSAMD5"|"RSA"|"DSA">
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.
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
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
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
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.
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
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 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.
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.
[1] Kolkman and Gieben, "DNSSEC Operational Practices", draft-ietf-dnsop-dnssec-operational-practices-01.txt (work in progress).
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.