From: Tony Finch Date: Thu, 31 Jan 2019 16:41:29 +0000 (+0000) Subject: cleanup: revamp the dnssec-dsfromkey man page and help output X-Git-Tag: v9.12.4rc1~28^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fb9bc8f87124368d0feae75b91cb5d086c7d0b1b;p=thirdparty%2Fbind9.git cleanup: revamp the dnssec-dsfromkey man page and help output * Alphabetize the option lists in the man page and help text * Make the synopses more consistent between the man page and help text, in particular the number of different modes * Group mutually exclusive options in the man page synopses, and order options so that it is more clear which are available in every mode * Expand the DESCRIPTION to provide an overview of the output modes and input modes * Improve cross-references between options * Leave RFC citations to the SEE ALSO section, and clarify which RFC specifies what * Clarify list of digest algorithms in dnssec-dsfromkey and dnssec-cds man pages (cherry picked from commit 6ca8e130ace087ce476d601c71f67a96220438e3) --- diff --git a/bin/dnssec/dnssec-cds.docbook b/bin/dnssec/dnssec-cds.docbook index af8cc6c2e8a..a86c0da6bda 100644 --- a/bin/dnssec/dnssec-cds.docbook +++ b/bin/dnssec/dnssec-cds.docbook @@ -144,9 +144,9 @@ record. This option has no effect when using CDS records. - The algorithm must be one of SHA-1 - (SHA1), SHA-256 (SHA256), GOST, or SHA-384 (SHA384). These - values are case insensitive. If no algorithm is specified, + The algorithm must be one of SHA-1, + SHA-256, SHA-384, or GOST. These values are case insensitive, + and hyphens may be omitted. If no algorithm is specified, the default is SHA-256. diff --git a/bin/dnssec/dnssec-dsfromkey.c b/bin/dnssec/dnssec-dsfromkey.c index f31c546622f..11c99d13a86 100644 --- a/bin/dnssec/dnssec-dsfromkey.c +++ b/bin/dnssec/dnssec-dsfromkey.c @@ -319,30 +319,27 @@ usage(void) ISC_PLATFORM_NORETURN_POST; static void usage(void) { fprintf(stderr, "Usage:\n"); - fprintf(stderr, " %s options [-K dir] keyfile\n\n", program); - fprintf(stderr, " %s options [-K dir] [-c class] -s dnsname\n\n", - program); - fprintf(stderr, " %s options -f zonefile (as zone name)\n\n", program); - fprintf(stderr, " %s options -f zonefile zonename\n\n", program); + fprintf(stderr, " %s [options] keyfile\n\n", program); + fprintf(stderr, " %s [options] -f zonefile [zonename]\n\n", program); + fprintf(stderr, " %s [options] -s dnsname\n\n", program); + fprintf(stderr, " %s [-h|-V]\n\n", program); fprintf(stderr, "Version: %s\n", VERSION); - fprintf(stderr, "Options:\n"); - fprintf(stderr, " -v \n"); - fprintf(stderr, " -V: print version information\n"); - fprintf(stderr, " -K : directory in which to find " - "key file or keyset file\n"); - fprintf(stderr, " -a algorithm: digest algorithm " - "(SHA-1, SHA-256, GOST or SHA-384)\n"); - fprintf(stderr, " -1: use SHA-1\n"); - fprintf(stderr, " -2: use SHA-256\n"); - fprintf(stderr, " -C: print CDS record\n"); - fprintf(stderr, " -l: add lookaside zone and print DLV records\n"); - fprintf(stderr, " -s: read keyset from keyset- file\n"); - fprintf(stderr, " -c class: rdata class for DS set (default: IN)\n"); - fprintf(stderr, " -T TTL\n"); - fprintf(stderr, " -f file: read keyset from zone file\n"); - fprintf(stderr, " -A: when used with -f, " - "include all keys in DS set, not just KSKs\n"); - fprintf(stderr, "Output: DS or DLV RRs\n"); + fprintf(stderr, "Options:\n" +" -1: digest algorithm SHA-1\n" +" -2: digest algorithm SHA-256\n" +" -a algorithm: digest algorithm (SHA-1, SHA-256, SHA-384 or GOST)\n" +" -A: include all keys in DS set, not just KSKs (-f only)\n" +" -c class: rdata class for DS set (default IN) (-f or -s only)\n" +" -C: print CDS records\n" +" -f zonefile: read keys from a zone file\n" +" -h: print help information\n" +" -K directory: where to find key or keyset files\n" +" -l zone: print DLV records in the given lookaside zone\n" +" -s: read keys from keyset- file\n" +" -T: TTL of output records (omitted by default)\n" +" -v level: verbosity\n" +" -V: print version information\n"); + fprintf(stderr, "Output: DS, DLV, or CDS RRs\n"); exit (-1); } diff --git a/bin/dnssec/dnssec-dsfromkey.docbook b/bin/dnssec/dnssec-dsfromkey.docbook index 4fdc507a94d..7f0039ebb1d 100644 --- a/bin/dnssec/dnssec-dsfromkey.docbook +++ b/bin/dnssec/dnssec-dsfromkey.docbook @@ -49,56 +49,108 @@ dnssec-dsfromkey - - - - - - + + + + + + + + + + + keyfile dnssec-dsfromkey - -s - - - - - - - + + + + + + + + + - + + + + dnsname + + + dnssec-dsfromkey + + + + + + + + + + + + + -s dnsname - + dnssec-dsfromkey - - - + + + + + DESCRIPTION - dnssec-dsfromkey - outputs the Delegation Signer (DS) resource record (RR), as defined in - RFC 3658 and RFC 4509, for the given key(s). + + The dnssec-dsfromkey command outputs DS (Delegation + Signer) resource records (RRs) and other similarly-constructed RRs: + with the option it outputs DLV (DNSSEC Lookaside + Validation) RRs; or with the it outputs CDS (Child + DS) RRs. + + + + The input keys can be specified in a number of ways: + + + By default, dnssec-dsfromkey reads a key file + named like Knnnn.+aaa+iiiii.key, as generated + by dnssec-keygen. + + + + With the + option, dnssec-dsfromkey reads keys from a zone file + or partial zone file (which can contain just the DNSKEY records). + + + + With the + option, dnssec-dsfromkey reads + a keyset- file, as generated + by dnssec-keygen . + + OPTIONS - -1 - Use SHA-1 as the digest algorithm (the default is to use - both SHA-1 and SHA-256). + An abbreviation for @@ -107,7 +159,7 @@ -2 - Use SHA-256 as the digest algorithm. + An abbreviation for @@ -116,40 +168,49 @@ -a algorithm - Select the digest algorithm. The value of - must be one of SHA-1 (SHA1), - SHA-256 (SHA256), GOST or SHA-384 (SHA384). - These values are case insensitive. + Specify a digest algorithm to use when converting DNSKEY + records to DS records. This option can be repeated, so + that multiple DS records are created for each DNSKEY + record. + + + The algorithm must be one of + SHA-1, SHA-256, or SHA-384. These values are case insensitive, + and the hyphen may be omitted. If no algorithm is specified, + the default is SHA-256. - -C - - - Generate CDS records rather than DS records. This is mutually - exclusive with generating lookaside records. - - + -A + + + Include ZSKs when generating DS records. Without this option, only + keys which have the KSK flag set will be converted to DS records + and printed. Useful only in zone file mode. + + - -T TTL + -c class - Specifies the TTL of the DS records. + Specifies the DNS class (default is IN). Useful only + in keyset or + zone file mode. - -K directory + -C - Look for key files (or, in keyset mode, - keyset- files) in - . + Generate CDS records rather than DS records. This is mutually + exclusive with the option for generating DLV + records. @@ -158,13 +219,14 @@ -f file - Zone file mode: in place of the keyfile name, the argument is - the DNS domain name of a zone master file, which can be read + Zone file mode: dnssec-dsfromkey's + final dnsname argument is + the DNS domain name of a zone whose master file can be read from . If the zone name is the same as , then it may be omitted. - If is set to "-", then + If file is "-", then the zone data is read from the standard input. This makes it possible to use the output of the dig command as input, as in: @@ -176,64 +238,62 @@ - -A - - - Include ZSKs when generating DS records. Without this option, - only keys which have the KSK flag set will be converted to DS - records and printed. Useful only in zone file mode. - - + -h + + + Prints usage information. + + - -l domain + -K directory - Generate a DLV set instead of a DS set. The specified - is appended to the name for each - record in the set. - The DNSSEC Lookaside Validation (DLV) RR is described - in RFC 4431. This is mutually exclusive with generating - CDS records. + Look for key files or keyset- files in + . - -s + -l domain - Keyset mode: in place of the keyfile name, the argument is - the DNS domain name of a keyset file. + Generate a DLV set instead of a DS set. The specified + domain is appended to the name for each + record in the set. + This is mutually exclusive with the option + for generating CDS records. - -c class + -s - Specifies the DNS class (default is IN). Useful only - in keyset or zone file mode. + Keyset mode: dnssec-dsfromkey's + final dnsname argument is the DNS + domain name used to locate a keyset- file. - + - -v level + -T TTL - Sets the debugging level. + Specifies the TTL of the DS records. By default the TTL is omitted. - + - -h + -v level - Prints usage information. + Sets the debugging level. @@ -254,21 +314,22 @@ To build the SHA-256 DS RR from the Kexample.com.+003+26160 - keyfile name, the following command would be issued: + keyfile name, you can issue the following command: dnssec-dsfromkey -2 Kexample.com.+003+26160 The command would print something like: - example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0 C5EA0B94 + example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94 + FILES - The keyfile can be designed by the key identification + The keyfile can be designated by the key identification Knnnn.+aaa+iiiii or the full file name Knnnn.+aaa+iiiii.key as generated by dnssec-keygen8. @@ -296,9 +357,11 @@ dnssec-signzone8 , BIND 9 Administrator Reference Manual, - RFC 3658, - RFC 4431. - RFC 4509. + RFC 3658 (DS RRs), + RFC 4431 (DLV RRs), + RFC 4509 (SHA-256 for DS RRs), + RFC 6605 (SHA-384 for DS RRs), + RFC 7344 (CDS and CDNSKEY RRs).