From 5aeec9bb28e7764b5efbb01d34f0c05b03b0675e Mon Sep 17 00:00:00 2001 From: Jim Reid Date: Tue, 27 Jun 2000 21:50:27 +0000 Subject: [PATCH] first draft of man pages on dnssec tools --- bin/dnssec/dnssec-keygen.8 | 282 +++++++++++++++++++++++++++++ bin/dnssec/dnssec-makekeyset.8 | 201 ++++++++++++++++++++ bin/dnssec/dnssec-signkey.8 | 157 ++++++++++++++++ bin/dnssec/dnssec-signzone.8 | 282 +++++++++++++++++++++++++++++ doc/man/dnssec/dnssec-keygen.8 | 282 +++++++++++++++++++++++++++++ doc/man/dnssec/dnssec-makekeyset.8 | 201 ++++++++++++++++++++ doc/man/dnssec/dnssec-signkey.8 | 157 ++++++++++++++++ doc/man/dnssec/dnssec-signzone.8 | 282 +++++++++++++++++++++++++++++ 8 files changed, 1844 insertions(+) create mode 100644 bin/dnssec/dnssec-keygen.8 create mode 100644 bin/dnssec/dnssec-makekeyset.8 create mode 100644 bin/dnssec/dnssec-signkey.8 create mode 100644 bin/dnssec/dnssec-signzone.8 create mode 100644 doc/man/dnssec/dnssec-keygen.8 create mode 100644 doc/man/dnssec/dnssec-makekeyset.8 create mode 100644 doc/man/dnssec/dnssec-signkey.8 create mode 100644 doc/man/dnssec/dnssec-signzone.8 diff --git a/bin/dnssec/dnssec-keygen.8 b/bin/dnssec/dnssec-keygen.8 new file mode 100644 index 0000000000..c5a0ed2f4e --- /dev/null +++ b/bin/dnssec/dnssec-keygen.8 @@ -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. diff --git a/bin/dnssec/dnssec-makekeyset.8 b/bin/dnssec/dnssec-makekeyset.8 new file mode 100644 index 0000000000..17febcbc95 --- /dev/null +++ b/bin/dnssec/dnssec-makekeyset.8 @@ -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 . diff --git a/bin/dnssec/dnssec-signkey.8 b/bin/dnssec/dnssec-signkey.8 new file mode 100644 index 0000000000..7eb7a5b56a --- /dev/null +++ b/bin/dnssec/dnssec-signkey.8 @@ -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 . diff --git a/bin/dnssec/dnssec-signzone.8 b/bin/dnssec/dnssec-signzone.8 new file mode 100644 index 0000000000..5a2221233c --- /dev/null +++ b/bin/dnssec/dnssec-signzone.8 @@ -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 . diff --git a/doc/man/dnssec/dnssec-keygen.8 b/doc/man/dnssec/dnssec-keygen.8 new file mode 100644 index 0000000000..c5a0ed2f4e --- /dev/null +++ b/doc/man/dnssec/dnssec-keygen.8 @@ -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. diff --git a/doc/man/dnssec/dnssec-makekeyset.8 b/doc/man/dnssec/dnssec-makekeyset.8 new file mode 100644 index 0000000000..17febcbc95 --- /dev/null +++ b/doc/man/dnssec/dnssec-makekeyset.8 @@ -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 . diff --git a/doc/man/dnssec/dnssec-signkey.8 b/doc/man/dnssec/dnssec-signkey.8 new file mode 100644 index 0000000000..7eb7a5b56a --- /dev/null +++ b/doc/man/dnssec/dnssec-signkey.8 @@ -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 . diff --git a/doc/man/dnssec/dnssec-signzone.8 b/doc/man/dnssec/dnssec-signzone.8 new file mode 100644 index 0000000000..5a2221233c --- /dev/null +++ b/doc/man/dnssec/dnssec-signzone.8 @@ -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 .