README-USAGE 2/25/1999

dnssigner has more flags than are comprehensible by humans.  The complete
list is at the end of this file and is also obtainable by typing:
    dnssigner -help

SIMPLE USAGE

Using traditional BIND DNS zone master files, there are two things
necessary as input to use dnssigner to sign a zone.  One is the
name of the input files and the other is the name of the keys to
use.

There are two kinds of data files used as input to the signing process. 
The zone master file, and a master file introduced by DNSSEC called the
parent file.  (A parent file contains output from the signing of the
parent zone, most importantly the signature by the parent of the zone's
keys).

Example.

Assume that the zone data is in f.zone, and the parent file is in
f.parent, then:

    dnssigner -zi f.zone -pi f.parent

will run the files through the signer.  The output defaults to
FINISH-ZONE and FINISH-GLUE.  This does no signing, but merges the
files, removes duplicates, generates NXTs and make signing instructions
for them (if the zone is judged to be signed).

Specifying a key is done with the -k1 flag or the -ks flag.  -k1 is followed by
a domain name owner of a key, the algorithm, and the key id.  -ks is followed
by a sequence of names, algorithms, and key ids until the end of the command
line.

Example.

Signing the above zone with the key of test., key id 27782, is done by:

    dnssigner -zi f.zone pi f.parent -k1 test. dsa 27782

To sign with both keys 27782 and 3696,

    dnssigner -zi f.zone -pi f.parent -ks test. dsa 27782 test. dsa 3696

OTHER SIGNIFICANT FLAGS

Input/output details

Other important flags are -[zp]i which specify the same three files
individually, -[zp]o which specify the output files.  -zo changes
the zone output from the default "FINISH-ZONE".  -po changes the
location of the parent files generated by the zone from FINISH-PARENT.

PARENT file handling

There are two forms of parent file generation.  One form is to place all
of the parent files in one file (good for zones with many delegations), the
other is to make a separate file for each delegation.  Since it is easier
to erase one file than potentially thousands, dnssigner defaults to the
single signer file.

-no-p1 turns single parent file generation off, -p1 turns it on. -po sets
the name of the single parent file (default FINISH-PARENT).

-ps turns on individual parent files, -no-ps turns it off.  -pd sets the
directory into which the individual files are put (default is the current
working directory).

NXT details

-no-n turns off RFC 2065 NXT processing, -n turns it on (the default).

Signing details

There are two time durations that are important to the handling of
signatures.  One is the duration until a newly generated signature
is set to expire.  The other is the duration in which existing
sgnatures will be considered to be expired.

-dur set the duration for which a signature is valid.  The time included
in the SIG RR expiration field is the current absolute time plus the
duration.  Wrapping around 32 bits is not a problem, time is considered
to be "circular."

-pt sets the period into the future in which SIGs expiring then are
considered to have expired.  Any signature that has an expiry time
in the past of the current time is thrown out, as well as signature
whose expiry time falls into the span between now and the -pt
duration.  The past is considered to be the time from now back to
2 to the 31st seconds ago, the rest is the future.

For more information on the flags, the "Compleat" list describes the
synatax of all flags.  The meanings can be found in RFC 2065 and the
drafts associated with the DNSSEC working group.

The Compleat dnssigner Usage list (except for deprecated flags):

Usage: dnssigner [any number of the following switches]
    Name                Switch  Arguments
Inputting files
    Input zone file     -zi     <file>

                                Specifies the zone data file.  The first
                                RR must be an SOA, the first record may be
                                found in a $INCLUDED file.

                                Default: START-ZONE

    Input parent file   -pi     <file>

                                Specifies the parent file received from the
                                parent zone to be used as input to this zone.
                                If specified, all records that would conflict
                                with it - apex upper nxt, keys, and sigs for
                                these are dropped.  If the UP policy is
                                specified, then the parent's KEY, NS, and glue
                                is also dropped.

                                Default: no parent file

Output files
    Zone out file       -zo     <file>

                                Specifies the file where signed zone data is
                                left.

                                Default: FINISH-ZONE

Parent File Generation
Note: there are two ways in which parent files are made, individual and bulk.
The two methods use independent switches - both can be used, neither can be
used, or just one.  By default, the bulk approach is used.

    Generate a Parent   -p1     none

                                Place all of the generated parent data for
                                the zone's delegation points into one file.
                                Separating lines are added to identify the
                                start and end of the information destined for
                                individual zones.
                                This is the "bulk" approach.

                                Default: this is done during the run.

    Parent out file     -po     <file>

                                Name of the file to hold all of the data.

                                Default: FINISH-PARENT

    Generate no Parent  -no-p1  none

                                Do not generate a single bulk parent file
                                during the run.

                                Default: the file is generated.  Use this
                                switch to turn the feature off.

    Generate Parents    -ps     none

                                Place the generated parent data into
                                individual files, named by def-directory/
                                zone.PARENT.

                                For large delegating zones, there will be many
                                files.  COM. would generate about 1-1/2 million
                                files (based on winter '98 data).

                                Default: this is not done, use the switch to
                                start this feature.

    Output dir          -pd     <directory>

                                Specifies directory for the individual
                                parent files.

                                Default: . (i.e., current working directory)

    Generate no Parents -no-ps  none

                                Suppress generation of individual parent files
                                for each delegation point.

                                Default: Generation is suppressed (this switch
                                is not needed unless -ps is specified earlier
                                in the line and the parents are now not wanted).

Signing Policy
    Down policy         -dn     none

                                Signs according to the DOWN policy - i.e.,
                                the apex does not sign the parent's keys,
                                the parent's keys and glue data are not
                                expected from nor written to parent files.

                                Default: DOWN policy

    Up policy           -up     none

                                Signs according to the UP policy - i.e.,
                                the apex signs the parent's keys,
                                the parent's keys and glue data are
                                expected from and written to parent files.

                                Note: this policy is now "not recommended."

                                Default: DOWN policy

    Parent name         -pa     <domain>

                                Specified the apex's parent zone.  If the keys
                                for this zone are known and the UP policy
                                is used, the apex zone keys sign the key.
                                If UP is used and this is not specified, then
                                the signer acts as if it does not otherwise
                                know the parent's identity.  This is equivalent
                                to the $PARENT directive (except that relative
                                domain names are treated as absolute names).

                                Default: unspecified

    Enforce Self-Signing -ess   none

                                This switch instructs the signer to make
                                sure each key in the file is signed by its
                                corresponding private key.  This is done
                                by implicitly adding $SIGNER directives
                                around each key set, adding those keys for
                                just the set.  If any private key is not
                                available, the $SIGNER directive remains
                                in the output file.

                                The intent of this feature is to insert
                                proof into DNS that the public key's
                                corresponding private key is held by
                                the owner (or at least the entity signing
                                the zone).

                                Default: not specified, ESS is not done

    No ESS              -no-ess none

                                Turns the feature off.  This flag is only
                                included as a counterpart to -ess.  The
                                only time it makes any sense is if you
                                have typed -ess on the run line and don't
                                want to backspace to remove it.

                                Default: ESS is not done, flag is not needed

NXT management
    Do NXT processing   -n      none

                                Generate NXT's for the zone, signing them
                                with the keys that sign the SOA record.  (If
                                none sign the SOA, no NXT's are signed.)

                                Default: NXT's are generated.  (This switch is
                                unnecessary unless the -no-n switch was
                                previously in the run command and now NXT's
                                are desired.)

    No NXT processing   -no-n   none

                                Suppress the generation of the NXT record.

                                Default: NXT's are generated, this switch
                                stops this.
SIG handling
    SIG duration        -dur    <ttl>

                                All SIG record generated are set to expire
                                at a the current time + duration.

                                <ttl> format is taken from the BIND definition
                                of TTL.  Numeric seconds is fine, as well as:
                                         <number> W - weeks
                                         <number> D - days
                                         <number> H - hours
                                         <number> M - minutes (not months!)
                                         <number> S - seconds

                                Default: 31 days

    Purge period        -pt     <ttl>

                                Specifies that all SIG records with expiration
                                times between the beginning of past up
                                through current time + the purge period are
                                treated as expired.  SIG records with
                                expiration times from current + purge period to
                                the end of the future are retained if they
                                are not proved invalid.

                                <ttl> format is taken from the BIND definition
                                of TTL.  Numeric seconds is fine, as well as:
                                         <number> W - weeks
                                         <number> D - days
                                         <number> H - hours
                                         <number> M - minutes (not months!)
                                         <number> S - seconds

                                The end of the future and beginning of the past
                                are points in time which have the same time
                                representation (one second apart) in a 32-bit
                                roll-over specification of time.  The end of
                                the future is 2 to the 31st power seconds from
                                the current time.

                                Default: 1 week

    Init key            -k1     <domain> <algorithm> <key id>

                                This adds the specified key (key owner,
                                algorithm, and key id) to the list of keys
                                with which to sign.  Equivalent to
                                $SIGNER ADD <><>.  This switch may appear
                                anywhere in the run command, it adds just
                                one key.

                                Default: keys are specified by $SIGNER
                                directives in the data files.  A zone
                                may elect not to use any keys.

    Init key list       -ks     <domain> <algorithm> <key id> [...] end of line

                                This adds the specified keys (key owner,
                                algorithm, and key id) to the list of keys
                                with which to sign.  Equivalent to
                                $SIGNER ADD <><>.  This switch is interpreted
                                as the last switch of the command line.  Any
                                number of keys can be specified.

                                Default: keys are specified by $SIGNER
                                directives in the data files.  A zone
                                may elect not to use any keys.

Output Controls
    Output Level        -l      <level>

                                level can be one of the following values:
                                Num or Mnemonic   Meaning
                                1      M(inimal)  Just errors
                                4      U(ser)     Errors and warnings
                                7      DEB(ugger) Source code loc, E & W
                                10     DEV(eloper)Source code loc and crypto

                                Default: user (aka 4)

    Hide Stats          -no-st  none

                                When specified, stifles the printing of
                                summary statistics at the end of the run.

                                Default: stats are not printed.

    Show Stats          -st     none

                                When specified, causes the printing of
                                summary statistics at the end of the run.

                                Default: stats are not printed.

Miscellaneous
    ORIGINal value      -or     <domain>

                                This is equivalent to $ORIGIN <domain>, except
                                that the terminating period is not needed in
                                the domain name.  Specifying an ORIGIN is only
                                mandatory for the root zones and other zones
                                using relative names in the zone files.  It
                                is recommended that the $ORIGIN <domain> be
                                put in the data file.

                                Default: unspecified

    Zone name           -zn     <domain>

                                This name is designated as the owner of the
                                SOA.  This switch is probably not important,
                                it can only be used for zones in the IN class.

                                Default: unspecified, the value is learned when
                                the SOA is processed.

    Print HELP          -help   Prints a long version of help and EXITS.

                                Default: switch is not specified.
