mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-31 06:25:31 +00:00
Code Issues Releases Wiki Activity

first draft of man pages on dnssec tools

Browse Source
This commit is contained in:
Jim Reid
2000-06-27 21:50:27 +00:00
parent 3b8403a20c
commit 5aeec9bb28
8 changed files with 1844 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

282
bin/dnssec/dnssec-keygen.8 Normal file
View File

@@ -0,0 +1,282 @@
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: dnssec-keygen.8,v 1.1 2000/06/27 21:50:27 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt DNSSEC-KEYGEN 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dnssec-keygen
.Nd key generation tool for DNSSEC
.Sh SYNOPSIS
.Nm dnssec-keygen
.Op Fl a Ar algorithm
.Op Fl b Ar keysize
.Op Fl e
.Op Fl g Ar generator
.Op Fl h
.Op Fl n Ar nametype
.Op Fl p Ar protocol-value
.Op Fl r Ar randomdev
.Op Fl s Ar strength-value
.Op Fl t Ar type
.Op Fl v Ar level
.Ar name
.Sh DESCRIPTION
.Nm dnssec-keygen
generates keys for DNSSEC, Secure DNS, as defined in RFC2065.
It also generates keys for use in Transaction Signatures, TSIG, which
is defined in RFC2845.
A short summary of the options and arguments to
.Nm dnssec-keygen
is printed by the
.Ar h
(help) option.
The
.Ar a ,
.Ar b ,
and
.Ar n
options and their arguments must be supplied when generating keys.
The domain name that the key has to be generated for is given by
.Ar name .
.Pp
The choice of encryption algorithm is selected by the
.Ar a
option to
.Nm dnssec-keygen .
.Ar algorithm
must be one of
.Dv RSA ,
.Dv RSAMD5 ,
.Dv DH ,
.Dv DSA
or
.Dv HMAC-MD5
to indicate that an RSA, RSAMD5, Diffie-Hellman, Digital Signature
Algorithm or HMAC-MD5 key is required.
The argument identifying the encryption algorithm is case-insensitive.
DNSSEC specifies DSA as a mandatory algorithm and RSA as a recommended one.
Implementations of TSIG must support HMAC-MD5.
.Pp
The number of bits in the key are determined by the
.Ar keysize
argument following the
.Ar b
option.
The choice of key size depends on the algorithm that is used.
RSA keys must be between 512 and 2048 bits.
Diffie-Hellman keys have to be between 128 and 4096 bits.
For DSA, the key size must be between 512 and 1024 bits and a multiple
of 64.
The length of an HMAC-MD5 key can be between 1 and 512 bits.
.Pp
The
.Ar -n
option specifies how the generated key will be used.
.Ar nametype
can be either
.Dv ZONE ,
.Dv HOST ,
.Dv ENTITY
or
.Dv USER
to indicate that the key will be used for signing a zone, host,
entity or user respectively.
.Ar nametype
is case-insensitive.
.Pp
The
.Ar e
option can only be used when generating RSA keys.
It tells
.Nm dnssec-keygen
to use a large exponent.
When creating Diffie-Hellman keys, the
.Ar g
option selects the Diffie-Hellman generator
.Ar generator
that is to be used.
The value of
.Ar generator
must be either 2 or 5.
.Pp
.Ar protocol-value
sets the protocol value for the generated key.
The default is 2 (email) for keys of type
.Dv USER
and 3 (DNSSEC) for all other key types.
Other possible values for this argument are listed in RFC2065 and its
successors.
.Pp
.Nm dnssec-keygen
uses random numbers to seed the process
of generating keys.
If the system does not have a pseudo-device like
.Pa /dev/random
for generating random numbers,
.Nm dnssec-keygen
will prompt for some keyboard input and use the time intervals between
keystrokes to provide some randomness.
The
.Ar r
option overrides this behaviour, making
.Nm dnssec-keygen
use
.Ar randomdev
as a source of random data.
.Pp
The strength value that the key will sign DNS resource records with is
given by
.Ar strength-value .
It should be a number between 0 and 15.
The default strength is zero.
.Pp
The
.Ar t
option indicates if the key is to be used for authentication or
confidentiality.
.Ar type
can be one of
.Dv AUTHCONF ,
.Dv NOAUTHCONF ,
.Dv NOAUTH
or
.Dv NOCONF .
The default is
.Dv AUTHCONF .
If type is
.Dv AUTHCONF
the key can be used for authentication and confidentialty.
Setting
.Ar type
to
.Dv NOAUTHCONF
indicates that the key cannot be used for authentication or confidentialty.
A value of
.Dv NOAUTH
means the key can be used for confidentiality but not for
authentication.
Similarly,
.Dv NOCONF
defines that the key cannot be used for confidentiality though it can
be used for authentication.
.Pp
The
.Ar v
option can be used to make
.Nm dnssec-keygen
more verbose.
As the debugging/tracing level
.Ar level
increases,
.Nm dnssec-keygen
generates increasingly detailed reports about what it is doing.
The default level is zero.
.Sh GENERATED KEYS
When
.Nm dnssec-keygen
completes it prints a string of the form
.Ar Knnnn.+aaa+iiiii
on the standard output.
This is an identification string for the key it has generated.
These strings can be supplied as arguments to
.Xr dnssec-makekeyset 8 .
.Pp
The
.Ar nnnn.
part is the dot-terminated domain name given by
.Ar name .
The DNSSEC algorithm identifier is indicated by
.Ar aaa -
001 for RSA, 002 for Diffie-Hellman, 003 for DSA or 157 for HMAC-MD5.
.Ar iiiii
is a five-digit number identifying the key.
.Pp
.Nm dnssec-keygen
creates two files.
The file names are adapted from the key identification string above.
They have names of the form:
.Ar Knnnn.+aaa+iiiii.key
and
.Ar Knnnn.+aaa+iiiii.private .
These contain the public and private parts of the key respectively.
The files generated by
.Nm dnssec-keygen
obey this naming convention to
make it easy for the signing tool
.Xr dnssec-signzone 8
to identify which file(s) have to be read to find the necessary
key(s) for generating or validating signatures.
.Pp
The
.Ar .key
file contains a KEY resource record that can be inserted into a zone file
with a
.Dv $INCLUDE
statement.
The private part of the key is in the
.Ar .private
file.
It contains details of the encryption algorithm that was used and any
relevant parameters: prime number, exponent, modulus, subprime, etc.
For obvious security reasons, this file does not have general read
permission.
The private part of the key is used by
.Xr dnssec-signzone 8
to generate signatures and the public part is used to verify the
signatures.
A
.Ar .private
key file is generated for a symmetric encryption algorithm such as
HDMAC-MD5, even though it has no private key.
.Sh EXAMPLE
To generate a 768-bit DSA key for the domain
.Dv example.com ,
the following command would be issued:
.Pp
.Dl # dnssec-keygen -a DSA -b 768 -n ZONE example.com
.Dl Kexample.com.+003+26160
.Pp
.Nm dnssec-keygen
has printed the key identification string
.Dv Kexample.com.+003+26160 ,
indicating a DSA key with identifier 26160.
It will also have created the files
.Pa Kexample.com.+003+26160.key
and
.Pa Kexample.com.+003+26160.private
containing respectively the public and private keys for the generated
DSA key.
.Sh FILES
.Pa /dev/random
.Sh SEE ALSO
.Xr RFC2065,
.Xr RFC2845,
.Xr dnssec-makekeyset 8 ,
.Xr dnssec-signkey 8 ,
.Xr dnssec-signzone 8 .
.Sh BUGS
The naming convention for the public and private key files is a little
clumsy.
It won't work for domain names that are longer than 236 characters
because of the
.Ar .+aaa+iiiii.private
suffix results in filenames that are too long for most
.Ux
systems.

201
bin/dnssec/dnssec-makekeyset.8 Normal file
View File

@@ -0,0 +1,201 @@
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: dnssec-makekeyset.8,v 1.1 2000/06/27 21:50:27 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt DNSSEC-MAKEKEYSET 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dnssec-makekeyset
.Nd produce a set of DNSSEC keys
.Sh SYNOPSIS
.Nm dnssec-makekeyset
.Op Fl h
.Op Fl s Ar start-time
.Op Fl e Ar end-time
.Op Fl t Ar TTL
.Op Fl r Ar randomdev
.Op Fl v level
.Ar keyfile ....
.Sh DESCRIPTION
.Nm dnssec-makekeyset
generates a key set from one or more keys created by
.Xr dnssec-keygen 8 .
It creates a file containing KEY and SIG records for some zone which
can then be signed by the zone's parent if the parent zone is
DNSSEC-aware.
.Ar keyfile
should be a key identification string as reported by
.Xr dnssec-keygen 8 :
i.e.
.Ar Knnnn.+aaa+iiiii
where
.Ar nnnn
is the name of the key,
.Ar aaa
is the encryption algorithm and
.Ar iiiii
is the key identifier.
Multiple
.Ar keyfile
arguments can be supplied when there are several keys to be combined
by
.Nm dnssec-makekeyset
into a key set.
.Pp
For any SIG records that are in the key set, the start time when the
SIG records become valid is specified with the
.Ar s
option.
.Ar start-time
can either be an absolute or relative date.
An absolute start time is indicated by a number in YYYYMMDDHHMMSS
notation: 20000530144500 denotes 14:45:00 UTC on May 30th, 2000.
A relative start time is supplied when
.Ar start-time
is given as +N: N seconds from the current time.
If no
.Ar s
option is supplied, the current date and time is used for the start
time of the SIG records.
.Pp
The expiry date for the SIG records can be set by the
.Ar e
option.
Note that in this context, the expiry date specifies when the SIG
records are no longer valid, not when they are deleted from caches on name
servers.
.Ar end-date
also represents an absolute or relative date.
YYYYMMDDHHMMSS notation is used as before to indicate an absolute date
and time.
When
.Ar end-date
is +N,
it indicates that the SIG records will expire in N seconds after their
start date.
If
.Ar end-date
is written as now+N,
the SIG records will expire in N seconds after the current time.
When no expiry date is set for the SIG records,
.Nm dnssec-makekeyset
defaults to an expire time of 30 days from the start time of the SIG
records.
.Pp
An alternate source of random data can be specified with the
.Ar r
option.
.Ar randomdev
is the name of the file to use to obtain random data.
By default
.Pa /dev/random
is used if this device is available.
If it is not provided by the operating system and no
.Ar r
option is used,
.Nm dnssec-makekeyset
will prompt the user for input from the keyboard and use the time
between keystrokes to derive some random data.
.Pp
The
.Ar t
option is followed by a time-to-live argument
.Ar TTL
which indicates the TTL value that will be assigned to the assembled KEY
and SIG records in the output file.
.Ar TTL
is expressed in seconds.
If no
.Ar t
option is provided,
.Nm dnssec-makekeyset
prints a warning and assumes that a default TTL of
3600 seconds was required.
.Pp
The
.Ar v
option can be used to make
.Nm dnssec-makekeyset
more verbose.
As the debugging/tracing level
.Ar level
increases,
.Nm dnssec-makekeyset
generates increasingly detailed reports about what it is doing.
The default level is zero.
An option of
.Ar h
gets
.Nm dnssec-makekeyset
to print a short summary of its options and arguments.
.Pp
If
.Nm dnssec-makekeyset
is successful, it creates a file name of the form
.Ar nnnn.keyset .
This file contains the KEY and SIG records for domain
.Dv nnnn ,
the domain name part from the key file identifier produced when
.Nm dnssec-keygen
created the domain's public and private keys.
The
.Ar .keyset
file can then be transferred to the DNS administrator of the parent
zone for them to sign the contents with
.Xr dnssec-signkey 8 .
.Sh EXAMPLE
The following command generates a key set for the DSA key for
.Dv example.com
that was shown in the
.Xr dnssec-keygen 8 man page.
The backslash is for typographic reasons and would not be provided on
the command line when running
.Nm dnssec-makekeyset .
.nf
.Dl # dnssec-makekeyset -t 86400 -s 20000701120000 \e\p
.Dl -e +2592000 Kexample.com.+003+26160
.fi
.Pp
.Nm dnssec-makekeyset
will create a file called
.Pa example.com.keyset
containing a SIG and KEY record for
.Dv example.com.
These records will have a TTL of 1 day: 86400 seconds.
The SIG record becomes valid at noon UTC on July 1st 2000 and expires
30 days (2592000 seconds) later.
.Pp
The DNS administrator for
.Dv example.com
could then send
.Pa example.com.keyset
to the DNS administrator for
.Dv .com
so that they could sign the resource records in the file.
This assumes that the
.Dv .com
zone is DNSSEC-aware and the administrators of the two zones have some
mechanism for authenticating each other and exchanging the keys and
signatures securely.
.Sh FILES
.Pa /dev/random .
.Sh SEE ALSO
.Xr RFC2065 ,
.Xr dnssec-keygen 8 ,
.Xr dnssec-signkey 8 .

157
bin/dnssec/dnssec-signkey.8 Normal file
View File

@@ -0,0 +1,157 @@
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: dnssec-signkey.8,v 1.1 2000/06/27 21:50:27 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt DNSSEC-SIGNKEY 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dnssec-signkey
.Nd DNSSEC keyset signing tool
.Sh SYNOPSIS
.Nm dnssec-signkey
.Op Fl h
.Op Fl p
.Op Fl r Ar randomdev
.Op Fl v Ar level
.Ar keyset
.Ar keyfile ...
.Sh DESCRIPTION
.Nm dnssec-signkey
is used to sign a key set for a child zone.
Typically this would be provided by a
.Ar .keyset
file generated by
.Xr dnssec-makekeyset 8 .
This provides a mechanism for a DNSSEC-aware zone to sign the keys of
any DNSSEC-aware child zones.
The child zone's key set gets signed with the zone keys for its parent
zone.
.Ar keyset
will be the pathname of the child zone's
.Ar .keyset
file.
Each
.Ar keyfile
argument will be a key identification string as reported by
.Xr dnssec-keygen 8
for the parent zone.
This allows the child's keys to be signed by more than 1 parent zone
key if these exist.
.Pp
The
.Ar p
option instructs
.Nm dnssec-signkey
to use pseudo-random data when signing the keys which is faster, but
less secure, than using genuinely random data for signing.
This option may be useful when there are many child zone keysets to
sign and CPU resources are limited.
It could also be used for short-lived keys and signatures that don't
require strengthening against cryptanalysis: for instance when the key
will be discarded long before it could be compromised.
.Pp
An alternate file for obtaining random data can be used with the
.Ar r
option.
.Ar filename
is the name of the file to use.
If no
.Ar r
option is used and the default file for random data
.Pa /dev/random
does not exist,
.Nm dnssec-signkey
will prompt for input from the keyboard.
The time between keystrokes will be measured and used to derive random
data.
.Pp
The
.Ar v
option can be used to make
.Nm dnssec-signkey
more verbose.
As the debugging/tracing level
.Ar level
increases,
.Nm dnssec-signkey
generates increasingly detailed reports about what it is doing.
The default level is zero.
.Pp
An option of
.Ar h
makes
.Nm dnssec-signkey
print a short summary of its command line options
and arguments.
.Pp
When
.Nm dnssec-signkey
completes successfully, it generates a file called
.Ar nnnn.signedkey
containing the signed keys for child zone
.Ar nnnn .
The keys from the
.Ar keyset
file will have been signed by the parent zone's key or keys which were
supplied as
.Ar keyfile
arguments.
This file should be sent to the DNS administrator of the child zone.
They arrange for its contents to be incorporated into the zone file
when it next gets signed with
.Xr dnssec-signzone 8 .
A copy of the generated
.Ar signedkey
file should be kept by the parent zone's DNS administrator.
.Sh EXAMPLE
The DNS administrator for a DNSSEC-aware
.Dv .com
zone would use the following command to make
.Nm dnssec-signkey
sign the
.Ar .keyset
file for
.Dv example.com
created in the example shown in the man page for
.Nm dnssec-makekeyset :
.Dl # dnssec-signkey example.com.keyset Kcom.+003+51944
.Pp
where
.Dv Kcom.+003+51944
was a key file identifier that was produced when
.Nm dnssec-keygen
generated a key for the
.Dv .com
zone.
.Pp
.Nm dnssec-signkey
will produce a file called
.Dv example.com.signedkey
which has the keys for
.Dv example.com
signed by the
.Dv com
zone's zone key.
.Sh FILES
.Pa /dev/random
.Sh SEE ALSO
.Xr RFC2065,
.Xr dnssec-keygen 8 ,
.Xr dnssec-makekeyset 8 ,
.Xr dnssec-signzone 8 .

282
bin/dnssec/dnssec-signzone.8 Normal file
View File

@@ -0,0 +1,282 @@
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: dnssec-signzone.8,v 1.1 2000/06/27 21:50:27 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt DNSSEC-SIGNZONE 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dnssec-signzone
.Nd DNSSEC zone signing tool
.Sh SYNOPSIS
.Nm dnssec-signzone
.Op Fl a
.Op Fl c Ar cycle-time
.Op Fl s Ar start-time
.Op Fl e Ar end-time
.Op Fl o Ar origin
.Op Fl f Ar output-file
.Op Fl p
.Op Fl r Ar randomdev
.Op Fl v Ar level
.Ar zonefile
.Op keyfile ....
.Sh DESCRIPTION
.Pp
.Nm dnssec-signzone
is used to sign a zone.
Any
.Ar .signedkey
files for the zone to be signed should be present in the current
directory, along with the keys that will be used to sign the zone.
If no
.Ar keyfile
arguments are supplied, the default behaviour is to use all the zone's
keys.
Providing specific
.Ar keyfile
arguments constrains
.Nm dnssec-signzone
to only use those keys for signing the zone.
Each
.Ar keyfile
argument would be an identification string for a key created with
.Xr dnssec-keygen 8 .
If the zone to be signed has any secure subzones, the
.Ar .signedkey
files for those subzones need to be available in the
current working directory used by
.Nm dnssec-signzone .
.Pp
.Ar zonefile
is the name of the unsigned zone file.
If the fully qualified domain name is not clear from the resource
records in the zone file because the owner-names are not fully
qualified and dot-terminated, the
.Ar o
option should be given.
.Ar origin
will be the fully qualified domain origin for the zone.
.Pp
.Nm dnssec-signzone
will generate NXT and SIG records for the zone and produce a signed
version of the zone.
If there is a
.Ar signedkey
file from the zone's parent, the parent's signatures will be
incorporated into the generated signed zone file.
Any delegation points in the signed zone will have their security
status defined - i.e. whether they are DNSSEC-aware or not.
.Pp
By default,
.Nm dnssec-signzone
generates a file called
.Ar zonefile.signed
containing the signed zone file.
This can be overridden by the
.Ar f
option.
Instead of this default file name, the signed zone file will be
written to
.Ar output-file .
.\" Don't hyphenate YYYYMMDDHHMMSS
.nh YYYYMMDDHHMMSS
.Pp
.Nm dnssec-signzone
does not verify the signatures by default.
The
.Ar a
option makes it verify the signatures it generated.
.Pp
The date and time when the generated
SIG records become valid can be specified with the
.Ar s
option.
.Ar start-time
can either be an absolute or relative date.
An absolute start time is indicated by a number in YYYYMMDDHHMMSS
notation: 20000530144500 denotes 14:45:00 UTC on May 30th, 2000.
A relative start time is supplied when
.Ar start-time
is given as +N: N seconds from the current time.
If no
.Ar s
option is supplied, the current date and time is used for the start
time of the SIG records.
.Pp
The expiry date for the SIG records can be set by the
.Ar e
option.
Note that in this context, the expiry date specifies when the SIG
records are no longer valid, not when they are deleted from caches on name
servers.
.Ar end-date
also represents an absolute or relative date.
YYYYMMDDHHMMSS notation is used as before to indicate an absolute date
and time.
When
.Ar end-date
is +N,
it indicates that the SIG records will expire in N seconds after their
start date.
If
.Ar end-date
is supplied as now+N,
the SIG records will expire in N seconds after the current time.
When no expiry date is set for the SIG records,
.Nm dnssec-signzone
defaults to an expire time of 30 days from the start time of the SIG
records.
.Pp
.Nm dnssec-signzone
can automatically re-sign records if their signatures expire before
the expiry date that applies for the current zone signing activity.
This would apply to a zone that has previously been signed.
The decision to generate a new SIG record is determined by the cycle
time.
If the current SIG record expires after the cycle time, it is left
alone.
If it expires before the cycle time, the SIG record is considered to
be close to expiry.
Therefore
.Nm dnssec-signzone
creates a new SIG record to replace then one that is about to expire.
.Pp
The default cycle time is quarter of the difference between the
signature end and start dates for the current invocation of
.Nm dnssec-signzone .
So if the
.Ar e
and
.Ar s
options are not specified,
.Nm dnssec-signzone
generates signatures that are valid for 30 days from the current
date by default.
The cycle time would be 7.5 days from the current date.
Therefore any SIG records that
were due to expire in that time would be replaced with new ones.
.Pp
The
.Ar c
option can be used to change the cycle time.
.Ar cycle-time
indicates the number of seconds from the current time that should be
used to
set the cycle time and
determine when fresh SIG records should be generated.
.Pp
The
.Ar p
option instructs
.Nm dnssec-signzone
to use pseudo-random data when signing the zone's resource records.
This is faster but less secure than using genuinely random data for signing.
This option may be useful when the zone has many resource records to be
signed and CPU resources are limited.
It could also be used for short-lived keys and signatures that don't
require strengthening against cryptanalysis: for instance when the signatures
will be discarded long before the signed data could be compromised.
.Pp
An alternate source of random data can be specified with the
.Ar r
option.
.Ar randomdev
is the name of the file to use to obtain random data.
By default
.Pa /dev/random
is used if this device is available.
If it is not provided by the operating system and no
.Ar r
option is used,
.Nm dnssec-signzone
will prompt the user for input from the keyboard and use the time
between keystrokes to derive some random data.
.Pp
An option of
.Ar h
makes
.Nm dnssec-signzone
print a short summary of its command line options
and arguments.
.Pp
The
.Ar v
option can be used to make
.Nm dnssec-signzone
more verbose.
As the debugging/tracing level
.Ar level
increases,
.Nm dnssec-signzone
generates increasingly detailed reports about what it is doing.
The default level is zero.
.Sh EXAMPLE
The example below shows how
.Nm dnssec-signzone
could be used to sign the
.Dv example.com
zone with the key that was generated in the example given in the
man page for
.Xr dnssec-keygen 8 .
The zone file for this zone is
.Dv example.com
and it can be assumed to contain fully qualified domain names which
means there is no need to use the
.Ar o
option to set the domain origin.
This zone file contains the keyset for
.Dv example.com
that was created by
.Xr dnssec-makekeyset 8 .
The zone's
.Ar .keyset
file was either appended to the zone file or
incorporated using a
.Dv $INCLUDE
statement.
If there was a
.Ar .signedkey
file from the parent zone - i.e.
.Dv example.com.signedkey
- it should be present in the current directory.
This allows the parent zone's signature to be included in the signed
version of the
.Dv example.com
zone.
.Pp
.Dl # dnssec-signzone example.com Kexample.com.+003+26160
.Pp
.Nm dnssec-signzone
will create a file called
.Dv example.com.signed ,
the signed version of the
.Dv example.com
zone.
This file can then be referenced in a
.Dv zone{}
statement in
.Pa /etc/named.conf
so that it can be loaded by the name server.
.Sh FILES
.Pa /dev/random
.Sh SEE ALSO
.Xr RFC2065,
.Xr dnssec-keygen 8 ,
.Xr dnssec-makekeyset 8 ,
.Xr dnssec-signkey 8 .

282
doc/man/dnssec/dnssec-keygen.8 Normal file
View File

@@ -0,0 +1,282 @@
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: dnssec-keygen.8,v 1.1 2000/06/27 21:50:27 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt DNSSEC-KEYGEN 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dnssec-keygen
.Nd key generation tool for DNSSEC
.Sh SYNOPSIS
.Nm dnssec-keygen
.Op Fl a Ar algorithm
.Op Fl b Ar keysize
.Op Fl e
.Op Fl g Ar generator
.Op Fl h
.Op Fl n Ar nametype
.Op Fl p Ar protocol-value
.Op Fl r Ar randomdev
.Op Fl s Ar strength-value
.Op Fl t Ar type
.Op Fl v Ar level
.Ar name
.Sh DESCRIPTION
.Nm dnssec-keygen
generates keys for DNSSEC, Secure DNS, as defined in RFC2065.
It also generates keys for use in Transaction Signatures, TSIG, which
is defined in RFC2845.
A short summary of the options and arguments to
.Nm dnssec-keygen
is printed by the
.Ar h
(help) option.
The
.Ar a ,
.Ar b ,
and
.Ar n
options and their arguments must be supplied when generating keys.
The domain name that the key has to be generated for is given by
.Ar name .
.Pp
The choice of encryption algorithm is selected by the
.Ar a
option to
.Nm dnssec-keygen .
.Ar algorithm
must be one of
.Dv RSA ,
.Dv RSAMD5 ,
.Dv DH ,
.Dv DSA
or
.Dv HMAC-MD5
to indicate that an RSA, RSAMD5, Diffie-Hellman, Digital Signature
Algorithm or HMAC-MD5 key is required.
The argument identifying the encryption algorithm is case-insensitive.
DNSSEC specifies DSA as a mandatory algorithm and RSA as a recommended one.
Implementations of TSIG must support HMAC-MD5.
.Pp
The number of bits in the key are determined by the
.Ar keysize
argument following the
.Ar b
option.
The choice of key size depends on the algorithm that is used.
RSA keys must be between 512 and 2048 bits.
Diffie-Hellman keys have to be between 128 and 4096 bits.
For DSA, the key size must be between 512 and 1024 bits and a multiple
of 64.
The length of an HMAC-MD5 key can be between 1 and 512 bits.
.Pp
The
.Ar -n
option specifies how the generated key will be used.
.Ar nametype
can be either
.Dv ZONE ,
.Dv HOST ,
.Dv ENTITY
or
.Dv USER
to indicate that the key will be used for signing a zone, host,
entity or user respectively.
.Ar nametype
is case-insensitive.
.Pp
The
.Ar e
option can only be used when generating RSA keys.
It tells
.Nm dnssec-keygen
to use a large exponent.
When creating Diffie-Hellman keys, the
.Ar g
option selects the Diffie-Hellman generator
.Ar generator
that is to be used.
The value of
.Ar generator
must be either 2 or 5.
.Pp
.Ar protocol-value
sets the protocol value for the generated key.
The default is 2 (email) for keys of type
.Dv USER
and 3 (DNSSEC) for all other key types.
Other possible values for this argument are listed in RFC2065 and its
successors.
.Pp
.Nm dnssec-keygen
uses random numbers to seed the process
of generating keys.
If the system does not have a pseudo-device like
.Pa /dev/random
for generating random numbers,
.Nm dnssec-keygen
will prompt for some keyboard input and use the time intervals between
keystrokes to provide some randomness.
The
.Ar r
option overrides this behaviour, making
.Nm dnssec-keygen
use
.Ar randomdev
as a source of random data.
.Pp
The strength value that the key will sign DNS resource records with is
given by
.Ar strength-value .
It should be a number between 0 and 15.
The default strength is zero.
.Pp
The
.Ar t
option indicates if the key is to be used for authentication or
confidentiality.
.Ar type
can be one of
.Dv AUTHCONF ,
.Dv NOAUTHCONF ,
.Dv NOAUTH
or
.Dv NOCONF .
The default is
.Dv AUTHCONF .
If type is
.Dv AUTHCONF
the key can be used for authentication and confidentialty.
Setting
.Ar type
to
.Dv NOAUTHCONF
indicates that the key cannot be used for authentication or confidentialty.
A value of
.Dv NOAUTH
means the key can be used for confidentiality but not for
authentication.
Similarly,
.Dv NOCONF
defines that the key cannot be used for confidentiality though it can
be used for authentication.
.Pp
The
.Ar v
option can be used to make
.Nm dnssec-keygen
more verbose.
As the debugging/tracing level
.Ar level
increases,
.Nm dnssec-keygen
generates increasingly detailed reports about what it is doing.
The default level is zero.
.Sh GENERATED KEYS
When
.Nm dnssec-keygen
completes it prints a string of the form
.Ar Knnnn.+aaa+iiiii
on the standard output.
This is an identification string for the key it has generated.
These strings can be supplied as arguments to
.Xr dnssec-makekeyset 8 .
.Pp
The
.Ar nnnn.
part is the dot-terminated domain name given by
.Ar name .
The DNSSEC algorithm identifier is indicated by
.Ar aaa -
001 for RSA, 002 for Diffie-Hellman, 003 for DSA or 157 for HMAC-MD5.
.Ar iiiii
is a five-digit number identifying the key.
.Pp
.Nm dnssec-keygen
creates two files.
The file names are adapted from the key identification string above.
They have names of the form:
.Ar Knnnn.+aaa+iiiii.key
and
.Ar Knnnn.+aaa+iiiii.private .
These contain the public and private parts of the key respectively.
The files generated by
.Nm dnssec-keygen
obey this naming convention to
make it easy for the signing tool
.Xr dnssec-signzone 8
to identify which file(s) have to be read to find the necessary
key(s) for generating or validating signatures.
.Pp
The
.Ar .key
file contains a KEY resource record that can be inserted into a zone file
with a
.Dv $INCLUDE
statement.
The private part of the key is in the
.Ar .private
file.
It contains details of the encryption algorithm that was used and any
relevant parameters: prime number, exponent, modulus, subprime, etc.
For obvious security reasons, this file does not have general read
permission.
The private part of the key is used by
.Xr dnssec-signzone 8
to generate signatures and the public part is used to verify the
signatures.
A
.Ar .private
key file is generated for a symmetric encryption algorithm such as
HDMAC-MD5, even though it has no private key.
.Sh EXAMPLE
To generate a 768-bit DSA key for the domain
.Dv example.com ,
the following command would be issued:
.Pp
.Dl # dnssec-keygen -a DSA -b 768 -n ZONE example.com
.Dl Kexample.com.+003+26160
.Pp
.Nm dnssec-keygen
has printed the key identification string
.Dv Kexample.com.+003+26160 ,
indicating a DSA key with identifier 26160.
It will also have created the files
.Pa Kexample.com.+003+26160.key
and
.Pa Kexample.com.+003+26160.private
containing respectively the public and private keys for the generated
DSA key.
.Sh FILES
.Pa /dev/random
.Sh SEE ALSO
.Xr RFC2065,
.Xr RFC2845,
.Xr dnssec-makekeyset 8 ,
.Xr dnssec-signkey 8 ,
.Xr dnssec-signzone 8 .
.Sh BUGS
The naming convention for the public and private key files is a little
clumsy.
It won't work for domain names that are longer than 236 characters
because of the
.Ar .+aaa+iiiii.private
suffix results in filenames that are too long for most
.Ux
systems.

201
doc/man/dnssec/dnssec-makekeyset.8 Normal file
View File

@@ -0,0 +1,201 @@
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: dnssec-makekeyset.8,v 1.1 2000/06/27 21:50:27 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt DNSSEC-MAKEKEYSET 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dnssec-makekeyset
.Nd produce a set of DNSSEC keys
.Sh SYNOPSIS
.Nm dnssec-makekeyset
.Op Fl h
.Op Fl s Ar start-time
.Op Fl e Ar end-time
.Op Fl t Ar TTL
.Op Fl r Ar randomdev
.Op Fl v level
.Ar keyfile ....
.Sh DESCRIPTION
.Nm dnssec-makekeyset
generates a key set from one or more keys created by
.Xr dnssec-keygen 8 .
It creates a file containing KEY and SIG records for some zone which
can then be signed by the zone's parent if the parent zone is
DNSSEC-aware.
.Ar keyfile
should be a key identification string as reported by
.Xr dnssec-keygen 8 :
i.e.
.Ar Knnnn.+aaa+iiiii
where
.Ar nnnn
is the name of the key,
.Ar aaa
is the encryption algorithm and
.Ar iiiii
is the key identifier.
Multiple
.Ar keyfile
arguments can be supplied when there are several keys to be combined
by
.Nm dnssec-makekeyset
into a key set.
.Pp
For any SIG records that are in the key set, the start time when the
SIG records become valid is specified with the
.Ar s
option.
.Ar start-time
can either be an absolute or relative date.
An absolute start time is indicated by a number in YYYYMMDDHHMMSS
notation: 20000530144500 denotes 14:45:00 UTC on May 30th, 2000.
A relative start time is supplied when
.Ar start-time
is given as +N: N seconds from the current time.
If no
.Ar s
option is supplied, the current date and time is used for the start
time of the SIG records.
.Pp
The expiry date for the SIG records can be set by the
.Ar e
option.
Note that in this context, the expiry date specifies when the SIG
records are no longer valid, not when they are deleted from caches on name
servers.
.Ar end-date
also represents an absolute or relative date.
YYYYMMDDHHMMSS notation is used as before to indicate an absolute date
and time.
When
.Ar end-date
is +N,
it indicates that the SIG records will expire in N seconds after their
start date.
If
.Ar end-date
is written as now+N,
the SIG records will expire in N seconds after the current time.
When no expiry date is set for the SIG records,
.Nm dnssec-makekeyset
defaults to an expire time of 30 days from the start time of the SIG
records.
.Pp
An alternate source of random data can be specified with the
.Ar r
option.
.Ar randomdev
is the name of the file to use to obtain random data.
By default
.Pa /dev/random
is used if this device is available.
If it is not provided by the operating system and no
.Ar r
option is used,
.Nm dnssec-makekeyset
will prompt the user for input from the keyboard and use the time
between keystrokes to derive some random data.
.Pp
The
.Ar t
option is followed by a time-to-live argument
.Ar TTL
which indicates the TTL value that will be assigned to the assembled KEY
and SIG records in the output file.
.Ar TTL
is expressed in seconds.
If no
.Ar t
option is provided,
.Nm dnssec-makekeyset
prints a warning and assumes that a default TTL of
3600 seconds was required.
.Pp
The
.Ar v
option can be used to make
.Nm dnssec-makekeyset
more verbose.
As the debugging/tracing level
.Ar level
increases,
.Nm dnssec-makekeyset
generates increasingly detailed reports about what it is doing.
The default level is zero.
An option of
.Ar h
gets
.Nm dnssec-makekeyset
to print a short summary of its options and arguments.
.Pp
If
.Nm dnssec-makekeyset
is successful, it creates a file name of the form
.Ar nnnn.keyset .
This file contains the KEY and SIG records for domain
.Dv nnnn ,
the domain name part from the key file identifier produced when
.Nm dnssec-keygen
created the domain's public and private keys.
The
.Ar .keyset
file can then be transferred to the DNS administrator of the parent
zone for them to sign the contents with
.Xr dnssec-signkey 8 .
.Sh EXAMPLE
The following command generates a key set for the DSA key for
.Dv example.com
that was shown in the
.Xr dnssec-keygen 8 man page.
The backslash is for typographic reasons and would not be provided on
the command line when running
.Nm dnssec-makekeyset .
.nf
.Dl # dnssec-makekeyset -t 86400 -s 20000701120000 \e\p
.Dl -e +2592000 Kexample.com.+003+26160
.fi
.Pp
.Nm dnssec-makekeyset
will create a file called
.Pa example.com.keyset
containing a SIG and KEY record for
.Dv example.com.
These records will have a TTL of 1 day: 86400 seconds.
The SIG record becomes valid at noon UTC on July 1st 2000 and expires
30 days (2592000 seconds) later.
.Pp
The DNS administrator for
.Dv example.com
could then send
.Pa example.com.keyset
to the DNS administrator for
.Dv .com
so that they could sign the resource records in the file.
This assumes that the
.Dv .com
zone is DNSSEC-aware and the administrators of the two zones have some
mechanism for authenticating each other and exchanging the keys and
signatures securely.
.Sh FILES
.Pa /dev/random .
.Sh SEE ALSO
.Xr RFC2065 ,
.Xr dnssec-keygen 8 ,
.Xr dnssec-signkey 8 .

157
doc/man/dnssec/dnssec-signkey.8 Normal file
View File

@@ -0,0 +1,157 @@
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: dnssec-signkey.8,v 1.1 2000/06/27 21:50:27 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt DNSSEC-SIGNKEY 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dnssec-signkey
.Nd DNSSEC keyset signing tool
.Sh SYNOPSIS
.Nm dnssec-signkey
.Op Fl h
.Op Fl p
.Op Fl r Ar randomdev
.Op Fl v Ar level
.Ar keyset
.Ar keyfile ...
.Sh DESCRIPTION
.Nm dnssec-signkey
is used to sign a key set for a child zone.
Typically this would be provided by a
.Ar .keyset
file generated by
.Xr dnssec-makekeyset 8 .
This provides a mechanism for a DNSSEC-aware zone to sign the keys of
any DNSSEC-aware child zones.
The child zone's key set gets signed with the zone keys for its parent
zone.
.Ar keyset
will be the pathname of the child zone's
.Ar .keyset
file.
Each
.Ar keyfile
argument will be a key identification string as reported by
.Xr dnssec-keygen 8
for the parent zone.
This allows the child's keys to be signed by more than 1 parent zone
key if these exist.
.Pp
The
.Ar p
option instructs
.Nm dnssec-signkey
to use pseudo-random data when signing the keys which is faster, but
less secure, than using genuinely random data for signing.
This option may be useful when there are many child zone keysets to
sign and CPU resources are limited.
It could also be used for short-lived keys and signatures that don't
require strengthening against cryptanalysis: for instance when the key
will be discarded long before it could be compromised.
.Pp
An alternate file for obtaining random data can be used with the
.Ar r
option.
.Ar filename
is the name of the file to use.
If no
.Ar r
option is used and the default file for random data
.Pa /dev/random
does not exist,
.Nm dnssec-signkey
will prompt for input from the keyboard.
The time between keystrokes will be measured and used to derive random
data.
.Pp
The
.Ar v
option can be used to make
.Nm dnssec-signkey
more verbose.
As the debugging/tracing level
.Ar level
increases,
.Nm dnssec-signkey
generates increasingly detailed reports about what it is doing.
The default level is zero.
.Pp
An option of
.Ar h
makes
.Nm dnssec-signkey
print a short summary of its command line options
and arguments.
.Pp
When
.Nm dnssec-signkey
completes successfully, it generates a file called
.Ar nnnn.signedkey
containing the signed keys for child zone
.Ar nnnn .
The keys from the
.Ar keyset
file will have been signed by the parent zone's key or keys which were
supplied as
.Ar keyfile
arguments.
This file should be sent to the DNS administrator of the child zone.
They arrange for its contents to be incorporated into the zone file
when it next gets signed with
.Xr dnssec-signzone 8 .
A copy of the generated
.Ar signedkey
file should be kept by the parent zone's DNS administrator.
.Sh EXAMPLE
The DNS administrator for a DNSSEC-aware
.Dv .com
zone would use the following command to make
.Nm dnssec-signkey
sign the
.Ar .keyset
file for
.Dv example.com
created in the example shown in the man page for
.Nm dnssec-makekeyset :
.Dl # dnssec-signkey example.com.keyset Kcom.+003+51944
.Pp
where
.Dv Kcom.+003+51944
was a key file identifier that was produced when
.Nm dnssec-keygen
generated a key for the
.Dv .com
zone.
.Pp
.Nm dnssec-signkey
will produce a file called
.Dv example.com.signedkey
which has the keys for
.Dv example.com
signed by the
.Dv com
zone's zone key.
.Sh FILES
.Pa /dev/random
.Sh SEE ALSO
.Xr RFC2065,
.Xr dnssec-keygen 8 ,
.Xr dnssec-makekeyset 8 ,
.Xr dnssec-signzone 8 .

282
doc/man/dnssec/dnssec-signzone.8 Normal file
View File

@@ -0,0 +1,282 @@
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: dnssec-signzone.8,v 1.1 2000/06/27 21:50:27 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt DNSSEC-SIGNZONE 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dnssec-signzone
.Nd DNSSEC zone signing tool
.Sh SYNOPSIS
.Nm dnssec-signzone
.Op Fl a
.Op Fl c Ar cycle-time
.Op Fl s Ar start-time
.Op Fl e Ar end-time
.Op Fl o Ar origin
.Op Fl f Ar output-file
.Op Fl p
.Op Fl r Ar randomdev
.Op Fl v Ar level
.Ar zonefile
.Op keyfile ....
.Sh DESCRIPTION
.Pp
.Nm dnssec-signzone
is used to sign a zone.
Any
.Ar .signedkey
files for the zone to be signed should be present in the current
directory, along with the keys that will be used to sign the zone.
If no
.Ar keyfile
arguments are supplied, the default behaviour is to use all the zone's
keys.
Providing specific
.Ar keyfile
arguments constrains
.Nm dnssec-signzone
to only use those keys for signing the zone.
Each
.Ar keyfile
argument would be an identification string for a key created with
.Xr dnssec-keygen 8 .
If the zone to be signed has any secure subzones, the
.Ar .signedkey
files for those subzones need to be available in the
current working directory used by
.Nm dnssec-signzone .
.Pp
.Ar zonefile
is the name of the unsigned zone file.
If the fully qualified domain name is not clear from the resource
records in the zone file because the owner-names are not fully
qualified and dot-terminated, the
.Ar o
option should be given.
.Ar origin
will be the fully qualified domain origin for the zone.
.Pp
.Nm dnssec-signzone
will generate NXT and SIG records for the zone and produce a signed
version of the zone.
If there is a
.Ar signedkey
file from the zone's parent, the parent's signatures will be
incorporated into the generated signed zone file.
Any delegation points in the signed zone will have their security
status defined - i.e. whether they are DNSSEC-aware or not.
.Pp
By default,
.Nm dnssec-signzone
generates a file called
.Ar zonefile.signed
containing the signed zone file.
This can be overridden by the
.Ar f
option.
Instead of this default file name, the signed zone file will be
written to
.Ar output-file .
.\" Don't hyphenate YYYYMMDDHHMMSS
.nh YYYYMMDDHHMMSS
.Pp
.Nm dnssec-signzone
does not verify the signatures by default.
The
.Ar a
option makes it verify the signatures it generated.
.Pp
The date and time when the generated
SIG records become valid can be specified with the
.Ar s
option.
.Ar start-time
can either be an absolute or relative date.
An absolute start time is indicated by a number in YYYYMMDDHHMMSS
notation: 20000530144500 denotes 14:45:00 UTC on May 30th, 2000.
A relative start time is supplied when
.Ar start-time
is given as +N: N seconds from the current time.
If no
.Ar s
option is supplied, the current date and time is used for the start
time of the SIG records.
.Pp
The expiry date for the SIG records can be set by the
.Ar e
option.
Note that in this context, the expiry date specifies when the SIG
records are no longer valid, not when they are deleted from caches on name
servers.
.Ar end-date
also represents an absolute or relative date.
YYYYMMDDHHMMSS notation is used as before to indicate an absolute date
and time.
When
.Ar end-date
is +N,
it indicates that the SIG records will expire in N seconds after their
start date.
If
.Ar end-date
is supplied as now+N,
the SIG records will expire in N seconds after the current time.
When no expiry date is set for the SIG records,
.Nm dnssec-signzone
defaults to an expire time of 30 days from the start time of the SIG
records.
.Pp
.Nm dnssec-signzone
can automatically re-sign records if their signatures expire before
the expiry date that applies for the current zone signing activity.
This would apply to a zone that has previously been signed.
The decision to generate a new SIG record is determined by the cycle
time.
If the current SIG record expires after the cycle time, it is left
alone.
If it expires before the cycle time, the SIG record is considered to
be close to expiry.
Therefore
.Nm dnssec-signzone
creates a new SIG record to replace then one that is about to expire.
.Pp
The default cycle time is quarter of the difference between the
signature end and start dates for the current invocation of
.Nm dnssec-signzone .
So if the
.Ar e
and
.Ar s
options are not specified,
.Nm dnssec-signzone
generates signatures that are valid for 30 days from the current
date by default.
The cycle time would be 7.5 days from the current date.
Therefore any SIG records that
were due to expire in that time would be replaced with new ones.
.Pp
The
.Ar c
option can be used to change the cycle time.
.Ar cycle-time
indicates the number of seconds from the current time that should be
used to
set the cycle time and
determine when fresh SIG records should be generated.
.Pp
The
.Ar p
option instructs
.Nm dnssec-signzone
to use pseudo-random data when signing the zone's resource records.
This is faster but less secure than using genuinely random data for signing.
This option may be useful when the zone has many resource records to be
signed and CPU resources are limited.
It could also be used for short-lived keys and signatures that don't
require strengthening against cryptanalysis: for instance when the signatures
will be discarded long before the signed data could be compromised.
.Pp
An alternate source of random data can be specified with the
.Ar r
option.
.Ar randomdev
is the name of the file to use to obtain random data.
By default
.Pa /dev/random
is used if this device is available.
If it is not provided by the operating system and no
.Ar r
option is used,
.Nm dnssec-signzone
will prompt the user for input from the keyboard and use the time
between keystrokes to derive some random data.
.Pp
An option of
.Ar h
makes
.Nm dnssec-signzone
print a short summary of its command line options
and arguments.
.Pp
The
.Ar v
option can be used to make
.Nm dnssec-signzone
more verbose.
As the debugging/tracing level
.Ar level
increases,
.Nm dnssec-signzone
generates increasingly detailed reports about what it is doing.
The default level is zero.
.Sh EXAMPLE
The example below shows how
.Nm dnssec-signzone
could be used to sign the
.Dv example.com
zone with the key that was generated in the example given in the
man page for
.Xr dnssec-keygen 8 .
The zone file for this zone is
.Dv example.com
and it can be assumed to contain fully qualified domain names which
means there is no need to use the
.Ar o
option to set the domain origin.
This zone file contains the keyset for
.Dv example.com
that was created by
.Xr dnssec-makekeyset 8 .
The zone's
.Ar .keyset
file was either appended to the zone file or
incorporated using a
.Dv $INCLUDE
statement.
If there was a
.Ar .signedkey
file from the parent zone - i.e.
.Dv example.com.signedkey
- it should be present in the current directory.
This allows the parent zone's signature to be included in the signed
version of the
.Dv example.com
zone.
.Pp
.Dl # dnssec-signzone example.com Kexample.com.+003+26160
.Pp
.Nm dnssec-signzone
will create a file called
.Dv example.com.signed ,
the signed version of the
.Dv example.com
zone.
This file can then be referenced in a
.Dv zone{}
statement in
.Pa /etc/named.conf
so that it can be loaded by the name server.
.Sh FILES
.Pa /dev/random
.Sh SEE ALSO
.Xr RFC2065,
.Xr dnssec-keygen 8 ,
.Xr dnssec-makekeyset 8 ,
.Xr dnssec-signkey 8 .