				DNSSEC TOOLS

Introduction
------------

The zonesigner command provides a simple interface for generating keys and
signing zones in support of DNSSEC environments.  Zonesigner was designed
around the procedures given in the Step-by-Step Guide.  As the Guide evolves,
Zonesigner will evolve to match.

A set of data files accompany zonesigner, as well as a collection of
additional tools for maintaining these data files.

Files
-----

In addition to generating keys and signing zones, it maintains information
on the key-generation and zone-signing processes.  The key table that is
updated at the end of each section is implemented as a keyrec file.

The keyrec file contains key/value pairs, organized into two main groups.
Key keyrecs list the parameters by which the keys were generated; zone keyrecs
list the parameters by which the zone was signed.  Zone keyrecs contain
references to the keys used to sign the zone, and key keyrecs reference the
zones to which the keys belong.

(The current implementation assumes that each key is only used by a single
zone.  This may not be a valid assumption, and things can be fixed if need
be.)

Keyrec files are text files that can be read and written using normal text
editors.  However, it is assumed that they will be maintained using the
DNSSEC-Tools commands.

A keyrec file may contain information on a single zone (and its keys) or on
multiple zones (and their keys.)

Keyrec files are documented in the .../modules/file-keyrec and in
.../modules/keyrec.pm.

Configuration Files
-------------------

/usr/local/etc/dnssec/dnssec-tools.conf is a system-wide configuration file
for the zonesigner family of tools.  An example configuration file follows:

	#
	# key management tools configuration
	#

	#
	# Settings for dnssec-keygen.
	#
	algorithm	rsasha1
	ksklength	2048
	zsklength	1024
	random		/dev/urandom

	#
	# Settings for dnssec-signzone.
	#
	endtime		+2592000	# RRSIGs good for thirty days.

If zonesigner-related parameters are not specified on the command line or in
a keyrec file, default values are taken from the configuration file.

An example configuration file is located in .../dnssec-tools/etc/dnssec/.
Copy that file /usr/local/etc/dnssec/dnssec-tools.conf.

Commands
--------

This following DNSSEC-Tools commands are for use in managing DNSSEC
environments.  Brief descriptions of these tools are given below.

	blinkenlights	Gives an elaborate graphical display of rollerd activity
			and allows some control of zones.

	bubbles		Gives a simple graphical display of rollerd activity.

	buildrealms	Construct a realms environment from a realms file and
			a set of files that will compose the realms.

	cleanarch	Cleans key archives.

	cleankrf	Cleans unreferenced key keyrecs from keyrec files.

	dtck            Runs validation checks on all the data files used by
			the DNSSEC-Tools scripts.

	dtconf          Displays the key/value pairs in a DNSSEC-Tools
			configuration file.

	dtconfchk	Verifies the validity of a DNSSEC-Tools config file.

	dtdefs		Display DNSSEC-Tools defaults.

	dtinitconf	Create a new DNSSEC-Tools configuration file from
			command-line options and defaults.

	dtrealms	Manages multiple simultaneous rollover environments.

	dtreqmods	Checks for Perl modules required by DNSSEC-Tools.

	dtupdkrf	Updates an old-format keyrec file to the current
			format.  The keyrec file format changes rarely,
			so this is not commonly needed.

	expchk		Checks a keyrec file for expired zones.

	fixkrf		Adjusts a keyrec file's data to account for moved
			encryption key files.

	genkrf		Generates a keyrec file using existing key signing
			key and/or zone signing keys.

	grandvizier	Graphic display of rollover environments.

	keyarch		Archives obsolete keys.

	keymod		Modifies key generation parameters in a keyrec file.

	krfcheck	Verifies the validity of a keyrec file.

	lights		Gives a very simple GUI summary of zone rollover states.

	lskrf		Lists the contents of a keyrec file.

	lsrealm		Lists the contents of a realms file.

	lsroll		Lists the contents of a rollrec file.

	realmchk	Verifies the validity of a realms file.

	realmctl	Control program for the dtrealms daemon.

	realminit	Generates realms records for a realm.

	realmset	Modifies the realm records in a realms file.

	rollchk		Verifies the validity of a rollrec file.

	rollctl		Control program for the rollover daemon.

	rollerd		The rollover daemon.

	rollinit	Generates rollrec records for domains.

	rolllog		Adds a log record to the rollover daemon's log file.

	rollrec-editor	GUI editor for managing rollrecs in rollrec files.

	rollset		Modifies the rollrec records in a rollrec file.

	signset-editor	GUI editor for managing signing sets in keyrec files.

	tachk		Reads a trusted-keys block from a named.conf file and
			performs queries to see if the configured trust
			anchors are still published by the zones.
			NOTE: This script additionally requires Net::DNS::SEC.

	timetrans	Converts time units (weeks, days, etc.) into the
			appropriate number of seconds.  Intended for use in
			calculating the end-time argument used by zonesigner
			and dnssec-signzone.

	zonesigner	Generates a set of keys for a zone and signs the zone
			with those keys.  This combines the functionality of
			dnssec-keygen and dnssec-signzone, recording relevant
			information in a keyrec file.


Modules
-------

This following are DNSSEC-Tools Perl modules for use in managing DNSSEC
environments.  Brief descriptions of these modules are given below.

	conf.pm		Parses configuration files.

	defaults.pm	Holds default values for DNSSEC-Tools.

	dnssectools.pm	Collection of disparate interfaces for DNSSEC-Tools.

	keyrec.pm	Reads and manipulates keyrec files.

	realm.pm	Reads and manipulates realms files.

	realmmgr.pm	Communication interfaces for dtrealms.

	rolllog.pm	Logging interfaces.

	rollmgr.pm	Communication interfaces for rollerd.

	rollrec.pm	Reads and manipulates rollrec files.

	timetrans.pm	Translates a seconds count into the appropriate
			time units (weeks, days, hours, minutes, seconds.)
			The module has one interface, which returns the
			translated value it was passed.  So, passing it
			the value 86800 will result in the string
			"1 day, 6 minutes, 40 seconds" being returned.

	tooloptions.pm	Sets command options, based on the config file,
			keyrec files, and command line options.
