path: root/contrib/bind/doc/man/dnssigner.1

.\" Copyright (c) 1996 by Internet Software Consortium
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
.\" CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, 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.
.\"
.\" $Id: dnssigner.1,v 8.2 1997/03/14 02:29:42 vixie Exp $
.\"
.Dd October 25, 1996
.Dt DNSSIGNER @CMD_EXT_U@
.Os BSD 4
.Sh NAME
.Nm dnssigner 
.Nd add signatures to DNS zone files
.Sh SYNOPSIS
.Nm dnssigner
.Op Cm signer-name Ar default_signer
.Op Cm boot-file Ar file
.Op Cm debug-file Ar file
.Op Cm out-dir Ar directory
.Op Cm seq-no Ar number
.Oo
.Cm expiration-time 
.Oo Po Cm + 
.Ns \&| 
.Ns Cm = 
.Pc Oc
.Ns Ar time
.Oc
.Op Cm hide 
.Op Cm noaxfr 
.Op Cm nosign 
.Op Cm verify 
.Op Cm update-zonekey 
.Op Fl d Ns Ar level
.Sh DESCRIPTION
.Ic Dnssigner
(Sign DNS zone database) is a tool to generate signatures
for DNS (Domain Name System) resource records.  It also generates
NXT records for each zone.
.Pp
.Bl -tag -width Fl
.It Cm signer-name Ar default_signer
Specifies a name of the key to use if no signer is defined using the
.Em Li $SIGNER  
directive in the boot files.
.It Cm boot-file Ar file
Specifies the control file for 
.Ic dnssigner , 
which is in the same format as the BIND-4 
.Pa named.boot 
file.
.It Cm debug-file Ar file
Redirect debug output to the specified 
.Ar file ; 
default is
.Pa signer_out 
in the current directory.
.It Cm out-dir Ar directory
Write signed files to thie specified
.Ar directory ; 
default is to use
.Pa /tmp .
.Pp
.Sy NOTE :  
Specify the full path to this directory; relative paths may not work.
.It Xo Cm expiration-time 
.Oo Po Cm + 
.Ns \&| 
.Ns Cm = 
.Pc Oc
.Ns Ar time
.Xc
Time when the signature records are to
expire.  Using either
.Dq Cm =
or 
.Em no 
sign before the 
.Ar time
argument
.Po i.e., 
.Do Op Cm = 
.Ns Ar time
.Dc 
.Pc , 
the 
.Ar time 
is interpreted as an absolute time in seconds when the records will expire.  
.Po Sy NOTE :
  All such times are interpreted as Universal Times.
.Pc 
With 
.Dq Cm +
specified 
.Pq i.e., Dq Cm + Ns Ar time ,
the
.Ar time 
time is interpreted as an offset into the future.
.Pp
If not specified on the command line, the default 
.Cm expiration-time
is 3600*24*30 sec (30 days).
.It Cm seq-no Ar number
Force the serial number in the SOA records to the specified value. 
If this parameter is not set, the serial number will be set to a value
based on the current time.
.It Cm hide 
This flag will cause NXT records in zones with wildcard
records to point to 
.Li *.<zone> 
as the next host. The purpose of this
flag is to hide all information about valid names in a zone.
.It Cm noaxfr
Turn of generation of zone transfer signature records,
which validate the transfer of an entire zone.
.It Cm nosign
When this flag is specified, the boot files are read, NXT
records are generated and zone file is written to the output
directory. No SIG records are generated. This flag is useful for
quickly checking the format of the data in the boot files, and to 
have boot files sorted into DNSSEC order.  
.It Cm verify
When this flag is present,
.Ic dnssigner
will verify all
signed records and print out a confirmation message for each SIG
verified. The main use of this flag is to see how long it takes to
generate each signature. 
.It Cm update-zonekey 
If this flag is specified, then the zonekeys used
to sign files will be updated with new records.  Specify this flag if
one or more of the keys have been updated.  If there are no zonekeys
specified in the boot files, this flag will insert them. Omitting
zonekeys will cause primary nameservers to reject the zone. 
.It Fl d Ns Ar level
Debug level to use for running 
.Ic dnssigner ;
these levels are the same as those used by 
.Xr @INDOT_U@NAMED @SYS_OPS_EXT_U@ 
.El
.Ss DETAILS
.Ic Dnssigner
reads BIND-4 
.Pa named.boot 
and zone files, adds SIG and NXT
records and writes out the records (to one file per zone, regardless of
how many include files the original zone was in).  The files generated by
.Ic dnssigner
are ordinary textual zone files and are then normally
loaded by 
.Xr @INDOT_U@NAMED @SYS_OPS_EXT_U@ 
to serve the zone.
.Ic Dnssigner
\fBrequires that the PRIVATE key(s) reside in the input directory\fP.
.Pp
Making manual changes to the output files is hazardous, because most
changes will invalidate one or more signatures contained therein.  This
will cause the zone to fail to load into 
.Xr @INDOT_U@NAMED @SYS_OPS_EXT_U@ , 
or will cause subsequent
failures in retrieving records from the zone.  It is far better to make
changes in 
.Ic dnssigner's
input files, and rerun 
.Ic dnssigner .
.Pp
When 
.Ic dnssigner
detects a delegation point, it creates a special file
.Pa <zone_name>.PARENT 
which contains the RR's the parent zone signs for the 
child zone (NS, KEY, NXT). The intent is that the child will include this
file when loading primary nameservers.  Similarly, each zone file ends
with the 
.Dq Li #include <zone_name>.PARENT 
command.  The records 
in the
.Pa .PARENT 
files are omitted from the SIG(AXFR) calculations as these
records usualy are on a different signing cycle.  
.Pp
The 
.Em Li Dq $SIGNER Op Ar keyname
directive can be used to change signers in a
zone.  If 
.Ar keyname 
is omitted, signing is turned off.  Keys are loaded the
first time the keys are accessed.  Only records that are signed by the
zone signer (the key that signs the SOA) are included in the SIG(AXFR)
calculation.  It is not generally recommended that multiple keys sign
records in the same zone, unless this is useful for dynamic updates.
.Sh ENVIRONMENT
No environmental variables are used.
.Sh SEE ALSO
.Xr @INDOT_U@NAMED @SYS_OPS_EXT_U@ ,
RSAREF documentation,
Internet-Draft 
.Em draft-ietf-dnssec-secext-10.txt
on Secure DNS, or its successor.
.Sh AUTHOR
Olafur Gudmundsson (ogud@tis.com)
.Sh ACKNOWLEDGMENTS
The underlying crypto math is done by the RSAREF or BSAFE libraries.