diff --git a/bin/dnssec/dnssec-keygen.8 b/bin/dnssec/dnssec-keygen.8 index 09cedeb2fe..8d186c5a78 100644 --- a/bin/dnssec/dnssec-keygen.8 +++ b/bin/dnssec/dnssec-keygen.8 @@ -14,7 +14,7 @@ .\" 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.3 2000/06/28 23:40:58 jim Exp $ +.\" $Id: dnssec-keygen.8,v 1.4 2000/07/26 00:47:13 bwelling Exp $ .\" .Dd Jun 30, 2000 .Dt DNSSEC-KEYGEN 8 @@ -25,12 +25,12 @@ .Nd key generation tool for DNSSEC .Sh SYNOPSIS .Nm dnssec-keygen -.Op Fl a Ar algorithm -.Op Fl b Ar keysize +.Fl a Ar algorithm +.Fl b Ar keysize .Op Fl e .Op Fl g Ar generator .Op Fl h -.Op Fl n Ar nametype +.Fl n Ar nametype .Op Fl p Ar protocol-value .Op Fl r Ar randomdev .Op Fl s Ar strength-value @@ -42,11 +42,13 @@ generates keys for DNSSEC, Secure DNS, as defined in RFC2535. It also generates keys for use in Transaction Signatures, TSIG, which is defined in RFC2845. +.Pp A short summary of the options and arguments to .Nm dnssec-keygen is printed by the .Fl h (help) option. +.Pp The .Fl a , .Fl b , @@ -62,7 +64,7 @@ option to .Nm dnssec-keygen . .Ar algorithm must be one of -.Dv RSAMD5 +.Dv RSAMD5 , .Dv DH , .Dv DSA or @@ -71,8 +73,7 @@ to indicate that an RSA, Diffie-Hellman, Digital Signature Algorithm or HMAC-MD5 key is required. An argument of .Dv RSA -can also be given. -It is equivalent to +can also be given, which is equivalent to .Dv RSAMD5 . The argument identifying the encryption algorithm is case-insensitive. DNSSEC specifies DSA as a mandatory algorithm and RSA as a recommended one. @@ -85,7 +86,7 @@ argument following the 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. +Diffie-Hellman keys must 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. @@ -124,7 +125,7 @@ that is to be used. The only supported values value of .Ar generator are 2 and 5. -If no Diffie-Hellman generator is supplied a known prime +If no Diffie-Hellman generator is supplied, a known prime from RFC2539 will be used if possible; otherwise 2 will be used as the generator. .Pp @@ -141,12 +142,12 @@ successors. .Nm dnssec-keygen uses random numbers to seed the process of generating keys. -If the system does not have a pseudo-device like +If the system does not have a .Pa /dev/random -for generating random numbers, +device that can be used for generating random numbers, .Nm dnssec-keygen -will prompt for some keyboard input and use the time intervals between -keystrokes to provide some randomness. +will prompt for keyboard input and use the time intervals between +keystrokes to provide randomness. The .Fl r option overrides this behaviour, making @@ -259,10 +260,12 @@ 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 +Both +.Ar .key +and .Ar .private -key file is generated for a symmetric encryption algorithm such as -HDMAC-MD5, even though it has no private key. +key files are generated for symmetric encryption algorithm such as +HMAC-MD5, even though the public and private key are equivalent. .Sh EXAMPLE To generate a 768-bit DSA key for the domain .Dv example.com , diff --git a/bin/dnssec/dnssec-makekeyset.8 b/bin/dnssec/dnssec-makekeyset.8 index ec66c37771..9998174666 100644 --- a/bin/dnssec/dnssec-makekeyset.8 +++ b/bin/dnssec/dnssec-makekeyset.8 @@ -14,7 +14,7 @@ .\" 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.3 2000/06/28 23:40:59 jim Exp $ +.\" $Id: dnssec-makekeyset.8,v 1.4 2000/07/26 00:47:14 bwelling Exp $ .\" .Dd Jun 30, 2000 .Dt DNSSEC-MAKEKEYSET 8 @@ -30,7 +30,7 @@ .Op Fl e Ar end-time .Op Fl t Ar TTL .Op Fl r Ar randomdev -.Op Fl v level +.Op Fl v Ar level .Ar keyfile .... .Sh DESCRIPTION .Nm dnssec-makekeyset @@ -125,8 +125,7 @@ If no .Fl t option is provided, .Nm dnssec-makekeyset -prints a warning and assumes that a default TTL of -3600 seconds was required. +prints a warning and uses a default TTL of 3600 seconds. .Pp The .Fl v @@ -139,9 +138,10 @@ increases, .Nm dnssec-makekeyset generates increasingly detailed reports about what it is doing. The default level is zero. -An option of +.Pp +The .Fl h -gets +option makes .Nm dnssec-makekeyset to print a short summary of its options and arguments. .Pp @@ -178,7 +178,7 @@ 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. +These records will have a TTL of 86400 seconds (1 day). The SIG record becomes valid at noon UTC on July 1st 2000 and expires 30 days (2592000 seconds) later. .Pp diff --git a/bin/dnssec/dnssec-signkey.8 b/bin/dnssec/dnssec-signkey.8 index 2bbefaca20..f7f80dc170 100644 --- a/bin/dnssec/dnssec-signkey.8 +++ b/bin/dnssec/dnssec-signkey.8 @@ -14,7 +14,7 @@ .\" 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.3 2000/06/28 23:41:00 jim Exp $ +.\" $Id: dnssec-signkey.8,v 1.4 2000/07/26 00:47:16 bwelling Exp $ .\" .Dd Jun 30, 2000 .Dt DNSSEC-SIGNKEY 8 @@ -55,31 +55,38 @@ This allows the child's keys to be signed by more than 1 parent zone key if these exist. .Pp The +.Fl h +option makes +.Nm dnssec-signkey +print a short summary of its command line options +and arguments. +.Pp +The .Fl p option instructs .Nm dnssec-signkey -to use pseudo-random data when signing the keys which is faster, but +to use pseudo-random data when signing the keys. This 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 of if the entropy source is limited. +sign or if the entropy source is limited. It could also be used for short-lived keys and signatures that don't -require strengthening against cryptanalysis: for instance when the key +require as much protection against cryptanalysis, such as 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 -.Fl r -option. -.Ar filename -is the name of the file to use. -If no -.Fl 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. +may need random numbers in the process of generating keys. +If the system does not have a +.Pa /dev/random +device that can be used for generating random numbers, +.Nm dnssec-signkey +will prompt for keyboard input and use the time intervals between +keystrokes to provide randomness. +The +.Fl r +option overrides this behaviour, making +.Nm dnssec-signkey +use +.Ar randomdev +as a source of random data. .Pp The .Fl v @@ -93,13 +100,6 @@ increases, generates increasingly detailed reports about what it is doing. The default level is zero. .Pp -An option of -.Fl 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 @@ -129,13 +129,14 @@ sign the file for .Dv example.com created in the example shown in the man page for -.Nm dnssec-makekeyset : +.Xr dnssec-makekeyset 8 : +.Pp .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 +.Xr dnssec-keygen 8 generated a key for the .Dv .com zone. diff --git a/bin/dnssec/dnssec-signzone.8 b/bin/dnssec/dnssec-signzone.8 index 3d69f65534..c0081f1b53 100644 --- a/bin/dnssec/dnssec-signzone.8 +++ b/bin/dnssec/dnssec-signzone.8 @@ -14,7 +14,7 @@ .\" 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.3 2000/06/28 23:41:01 jim Exp $ +.\" $Id: dnssec-signzone.8,v 1.4 2000/07/26 00:47:17 bwelling Exp $ .\" .Dd Jun 30, 2000 .Dt DNSSEC-SIGNZONE 8 @@ -46,8 +46,8 @@ 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. +arguments are supplied, the default behaviour is to use all of the zone's +keys that are present in the current directory. Providing specific .Ar keyfile arguments constrains @@ -182,29 +182,30 @@ determine when fresh SIG records should be generated. The .Fl 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 the entropy source is limited. +.Nm dnssec-signkey +to use pseudo-random data when signing the keys. This 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 or if the entropy source is 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. +require as much protection against cryptanalysis, such as when the key +will be discarded long before it could be compromised. .Pp -An alternate source of random data can be specified with the -.Fl 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 -.Fl 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. +may need random numbers in the process of signing the zone. +If the system does not have a +.Pa /dev/random +device that can be used for generating random numbers, +.Nm dnssec-signzone +will prompt for keyboard input and use the time intervals between +keystrokes to provide randomness. +The +.Fl r +option overrides this behaviour, making +.Nm dnssec-signzone +use +.Ar randomdev +as a source of random data. .Pp An option of .Fl h diff --git a/doc/man/dnssec/dnssec-keygen.8 b/doc/man/dnssec/dnssec-keygen.8 index 09cedeb2fe..8d186c5a78 100644 --- a/doc/man/dnssec/dnssec-keygen.8 +++ b/doc/man/dnssec/dnssec-keygen.8 @@ -14,7 +14,7 @@ .\" 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.3 2000/06/28 23:40:58 jim Exp $ +.\" $Id: dnssec-keygen.8,v 1.4 2000/07/26 00:47:13 bwelling Exp $ .\" .Dd Jun 30, 2000 .Dt DNSSEC-KEYGEN 8 @@ -25,12 +25,12 @@ .Nd key generation tool for DNSSEC .Sh SYNOPSIS .Nm dnssec-keygen -.Op Fl a Ar algorithm -.Op Fl b Ar keysize +.Fl a Ar algorithm +.Fl b Ar keysize .Op Fl e .Op Fl g Ar generator .Op Fl h -.Op Fl n Ar nametype +.Fl n Ar nametype .Op Fl p Ar protocol-value .Op Fl r Ar randomdev .Op Fl s Ar strength-value @@ -42,11 +42,13 @@ generates keys for DNSSEC, Secure DNS, as defined in RFC2535. It also generates keys for use in Transaction Signatures, TSIG, which is defined in RFC2845. +.Pp A short summary of the options and arguments to .Nm dnssec-keygen is printed by the .Fl h (help) option. +.Pp The .Fl a , .Fl b , @@ -62,7 +64,7 @@ option to .Nm dnssec-keygen . .Ar algorithm must be one of -.Dv RSAMD5 +.Dv RSAMD5 , .Dv DH , .Dv DSA or @@ -71,8 +73,7 @@ to indicate that an RSA, Diffie-Hellman, Digital Signature Algorithm or HMAC-MD5 key is required. An argument of .Dv RSA -can also be given. -It is equivalent to +can also be given, which is equivalent to .Dv RSAMD5 . The argument identifying the encryption algorithm is case-insensitive. DNSSEC specifies DSA as a mandatory algorithm and RSA as a recommended one. @@ -85,7 +86,7 @@ argument following the 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. +Diffie-Hellman keys must 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. @@ -124,7 +125,7 @@ that is to be used. The only supported values value of .Ar generator are 2 and 5. -If no Diffie-Hellman generator is supplied a known prime +If no Diffie-Hellman generator is supplied, a known prime from RFC2539 will be used if possible; otherwise 2 will be used as the generator. .Pp @@ -141,12 +142,12 @@ successors. .Nm dnssec-keygen uses random numbers to seed the process of generating keys. -If the system does not have a pseudo-device like +If the system does not have a .Pa /dev/random -for generating random numbers, +device that can be used for generating random numbers, .Nm dnssec-keygen -will prompt for some keyboard input and use the time intervals between -keystrokes to provide some randomness. +will prompt for keyboard input and use the time intervals between +keystrokes to provide randomness. The .Fl r option overrides this behaviour, making @@ -259,10 +260,12 @@ 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 +Both +.Ar .key +and .Ar .private -key file is generated for a symmetric encryption algorithm such as -HDMAC-MD5, even though it has no private key. +key files are generated for symmetric encryption algorithm such as +HMAC-MD5, even though the public and private key are equivalent. .Sh EXAMPLE To generate a 768-bit DSA key for the domain .Dv example.com , diff --git a/doc/man/dnssec/dnssec-makekeyset.8 b/doc/man/dnssec/dnssec-makekeyset.8 index ec66c37771..9998174666 100644 --- a/doc/man/dnssec/dnssec-makekeyset.8 +++ b/doc/man/dnssec/dnssec-makekeyset.8 @@ -14,7 +14,7 @@ .\" 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.3 2000/06/28 23:40:59 jim Exp $ +.\" $Id: dnssec-makekeyset.8,v 1.4 2000/07/26 00:47:14 bwelling Exp $ .\" .Dd Jun 30, 2000 .Dt DNSSEC-MAKEKEYSET 8 @@ -30,7 +30,7 @@ .Op Fl e Ar end-time .Op Fl t Ar TTL .Op Fl r Ar randomdev -.Op Fl v level +.Op Fl v Ar level .Ar keyfile .... .Sh DESCRIPTION .Nm dnssec-makekeyset @@ -125,8 +125,7 @@ If no .Fl t option is provided, .Nm dnssec-makekeyset -prints a warning and assumes that a default TTL of -3600 seconds was required. +prints a warning and uses a default TTL of 3600 seconds. .Pp The .Fl v @@ -139,9 +138,10 @@ increases, .Nm dnssec-makekeyset generates increasingly detailed reports about what it is doing. The default level is zero. -An option of +.Pp +The .Fl h -gets +option makes .Nm dnssec-makekeyset to print a short summary of its options and arguments. .Pp @@ -178,7 +178,7 @@ 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. +These records will have a TTL of 86400 seconds (1 day). The SIG record becomes valid at noon UTC on July 1st 2000 and expires 30 days (2592000 seconds) later. .Pp diff --git a/doc/man/dnssec/dnssec-signkey.8 b/doc/man/dnssec/dnssec-signkey.8 index 2bbefaca20..f7f80dc170 100644 --- a/doc/man/dnssec/dnssec-signkey.8 +++ b/doc/man/dnssec/dnssec-signkey.8 @@ -14,7 +14,7 @@ .\" 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.3 2000/06/28 23:41:00 jim Exp $ +.\" $Id: dnssec-signkey.8,v 1.4 2000/07/26 00:47:16 bwelling Exp $ .\" .Dd Jun 30, 2000 .Dt DNSSEC-SIGNKEY 8 @@ -55,31 +55,38 @@ This allows the child's keys to be signed by more than 1 parent zone key if these exist. .Pp The +.Fl h +option makes +.Nm dnssec-signkey +print a short summary of its command line options +and arguments. +.Pp +The .Fl p option instructs .Nm dnssec-signkey -to use pseudo-random data when signing the keys which is faster, but +to use pseudo-random data when signing the keys. This 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 of if the entropy source is limited. +sign or if the entropy source is limited. It could also be used for short-lived keys and signatures that don't -require strengthening against cryptanalysis: for instance when the key +require as much protection against cryptanalysis, such as 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 -.Fl r -option. -.Ar filename -is the name of the file to use. -If no -.Fl 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. +may need random numbers in the process of generating keys. +If the system does not have a +.Pa /dev/random +device that can be used for generating random numbers, +.Nm dnssec-signkey +will prompt for keyboard input and use the time intervals between +keystrokes to provide randomness. +The +.Fl r +option overrides this behaviour, making +.Nm dnssec-signkey +use +.Ar randomdev +as a source of random data. .Pp The .Fl v @@ -93,13 +100,6 @@ increases, generates increasingly detailed reports about what it is doing. The default level is zero. .Pp -An option of -.Fl 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 @@ -129,13 +129,14 @@ sign the file for .Dv example.com created in the example shown in the man page for -.Nm dnssec-makekeyset : +.Xr dnssec-makekeyset 8 : +.Pp .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 +.Xr dnssec-keygen 8 generated a key for the .Dv .com zone. diff --git a/doc/man/dnssec/dnssec-signzone.8 b/doc/man/dnssec/dnssec-signzone.8 index 3d69f65534..c0081f1b53 100644 --- a/doc/man/dnssec/dnssec-signzone.8 +++ b/doc/man/dnssec/dnssec-signzone.8 @@ -14,7 +14,7 @@ .\" 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.3 2000/06/28 23:41:01 jim Exp $ +.\" $Id: dnssec-signzone.8,v 1.4 2000/07/26 00:47:17 bwelling Exp $ .\" .Dd Jun 30, 2000 .Dt DNSSEC-SIGNZONE 8 @@ -46,8 +46,8 @@ 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. +arguments are supplied, the default behaviour is to use all of the zone's +keys that are present in the current directory. Providing specific .Ar keyfile arguments constrains @@ -182,29 +182,30 @@ determine when fresh SIG records should be generated. The .Fl 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 the entropy source is limited. +.Nm dnssec-signkey +to use pseudo-random data when signing the keys. This 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 or if the entropy source is 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. +require as much protection against cryptanalysis, such as when the key +will be discarded long before it could be compromised. .Pp -An alternate source of random data can be specified with the -.Fl 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 -.Fl 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. +may need random numbers in the process of signing the zone. +If the system does not have a +.Pa /dev/random +device that can be used for generating random numbers, +.Nm dnssec-signzone +will prompt for keyboard input and use the time intervals between +keystrokes to provide randomness. +The +.Fl r +option overrides this behaviour, making +.Nm dnssec-signzone +use +.Ar randomdev +as a source of random data. .Pp An option of .Fl h