$Id: README 3150 2010-04-08 11:36:13Z jakob $


This is a collection of tools, that together implement a pipelined
DNSSEC signer. These tools are used by the OpenDNSSEC signer engine to
create signed DNSSEC zones from unsigned zone data.

It is work in progress.

There are no man pages (yet?), so the pipeline is described below

BUILD INSTRUCTIONS
------------------

The signer make will also build these tools.

However, if you wish to compile them on your own, you can use:
autoreconf
./configure --with-ldns=<ldns dir>
make
(make install)



USAGE INSTRUCTIONS
------------------

Currently, the complete signer is implemented as a series of separate
tools, that each read in a (part of a) zone in BIND-style text format,
and output that zone with the necessary changes, again in text format.

To simply sign a zone, the following steps are needed:

1 Zone Reading (sorting, stripping, and optional NSEC3PARAM addition)
2 NSEC Addition
3 RRSIG Addition
4 Finalization

If DNSKEY records need to be added, this can be done with
create_dnskey, see Other tools below.

Step 3 can be called again on its own output, so that zones can be
re-signed.

1 Sorting
---------

Apart from the quicksorter, and the extra tools described below, the other
tools in the pipeline all expect that the data they receive is sorted
for their needs. In a normal signing operation, this means that the
zone must be sorted in canonical form, ie. the names must be sorted, 
and within each name the resource records must be sorted. 

In the case of NSEC3 denial-of-existence, the names must be sorted
in 'nsec3'-space, and within each name, the resource records must be
sorted in canonical order.

To achieve this, the tool 'quicksorter' can be used. Use 'quicksorter -h'
to see the specific options.

The quicksorter tool will also filter out glue records, and flag empty
non-terminals.

Glue records will be given to the output in the form
; glue: <Resource Record>
So that later steps will ignore these records (; means comments in
default zone format). The finalizer at step 4 will remove the comment
part so that the final output zone will have the glue data again.

There are two types of empty non-terminals (ENTs), 'normal' ENTs, and
'NS' ENTs. NS ENTs are empty non-terminals that lead to a name where
only NS Resource records exist (while normal ENTs lead to ojne where
other data is present). Normally, the quicksorter will ignore empty
non-terminals. However, if the zone is sorted in NSEC3 space, empty
non-terminals will be marked and passed on, so the nsecifier can create
NSEC3 records for them. They will be of the form:
; Empty non-terminal: <name>
If NSEC3 opt-out is also used, NS ENTs are also marked;
; Empty non-terminal to NS: <name>
(These ENTs should *not* get an NSEC3 record).


3 NSEC Addition
---------------

To create a fully signed zone, NSEC(3) records must be added.

This is done by the zone reader. Depending on the signer configuration, 
NSEC or NSEC3 records are added.

4 RRSIG Addition
----------------

And finally, the signature resource records must be added this is done
with the tool 'signer'. It has the following command-line arguments:
-c <config file>:  The OpenDNSSEC configuration file that contains
                   the HSM modules etc.
-f <input file>:   From this file, commands and input RRsets are read.
                   If this argument is not given, stdin is used
-h:                Show a usage screen
-p: <signed file>: If this file is given and exists it should point to
                   a previous output file of the signer tool.
                   Previously generated RRSIGs that do not need to be
                   regenerated (yet) are read from this file, to speed
                   up re-signing operations.
                   This MUST be the DIRECT output of the signer, NOT
                   the output from the finalizer.
-w: <output file>: The signed zone file will be written to this file.
                   This MUST NOT be the same file as either the file for
                   the -f or the -p flag, since the signer will write
                   output before reading in all input.
-r:                Makes the signer print the number of signatures it
                   created to stderr. On success, this should always
                   be 1 or more, since the SOA record is always re-signed.

Specific signing commands are passed in-line; with the following commands:
:add_ksk <key id> <key algorithm nr> <key flags>
    adds a KSK to be used to generate signatures for the DNSKEY RRset
:add_zsk <key id> <key algorithm nr> <key flags>
    adds a KSK to be used to generate signatures for all non-DNSKEY
    RRsets
:inception <YYYYMMDD[HHmmss]>
    sets the inception date for signatures
:expiration <YYYYMMDD[HHmmss]>
    sets the expiration date for signatures
:expiration_denial <YYYYMMDD[HHmmss]>
    sets the expiration date for signatures for NSEC and NSEC3 records
    if not set, the value from :expiration will be used for denial sigs
:expiration_keys <YYYYMMDD[HHmmss]>
    sets the expiration date for signatures for DNSKEY records
    if not set, the value from :expiration will be used for key sigs
:jitter <int value>
    sets the jitter value for expiration dates
:refresh <YYYYMMDD[HHmmss]>
    sets the refresh date; signatures with an expiration date before
    this value are dropped and regenerated
:origin <dname>
    sets the zone name for the current zone (mandatory)
:soa_ttl <int>
    sets the TTL for the SOA record, this will override the TTL of the
    SOA in the input file
:soa_serial <int>
    sets the serial value for the SOA record, this will override the
    serial value of the SOA in the input file
:soa_minimum <int>
    sets the minimum value for the SOA record, this will override the
    minimum value of the SOA in the input file
:stop
    stop the signer (it will also stop if EOL is read in the input file)

If an input line starts with ';', it is read as a comment, and will
simply be copied to the output. Lines starting with ';' in a previously
signed zone are dropped.

Otherwise, the input lines are parsed as Resource Records. The signer
will read an RRset from the input file, and check whether the input file
has signatures for the keys that are specified. If a previously signed
zone file is given, it will simultaneously be parsed for existing RRSIG
records. If there are no RRSIG records for a specific key, or if the
expiration date of said signatures falls before the 'refresh' value,
new signatures are generated.

This tool will also add some statistics to the file (sign time and 
signature counts).


Finalizer
---------

Due to the sorting at the beginning of step 1, the SOA resource record
will not be the first in the zone file anymore. Some DNS servers cannot
cope with that, so one of the tasks of the finalizer is to place the
SOA record as the very first one in its output.

It will also re-add the glue records that are passed to it in the form
; Glue: <Resource Record>
The string "; Glue: " will be removed, readding it to zone.

It will also re-add the records that were set aside as being opt-out 
records (stored in a seperate file <zone>.optout).

Other tools
-----------

There is a tool to create a DNSKEY RR from a PKCS11 key id and
algorithm, called 'create_dnskey'. It takes the same arguments
as 'signer', but just prints out a DNSKEY RR for each key
specified.

There is a tool to get the SOA SERIAL from a zone file, called 'get_serial'.
Use 'get_serial -h' to see the specific options.
