ComputerSurge/bind9
3
0
Fork 0
Code Pull Requests 1 Activity

Merge branch 'u/fanf2/dsfromkey-man' into 'master'

Browse Source 
cleanup: revamp the dnssec-dsfromkey man page and help output

See merge request isc-projects/bind9!1437
This commit is contained in:
Evan Hunt
2019-02-05 22:48:20 -05:00
parent cd87d6152a 6ca8e130ac
commit c22894a3d3
3 changed files with 176 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
bin/dnssec/dnssec-cds.docbook
View File

@@ -144,9 +144,9 @@
record. This option has no effect when using CDS records.
</para>
<para>
The <replaceable>algorithm</replaceable> must be one of SHA-1
(SHA1), SHA-256 (SHA256), or SHA-384 (SHA384). These
values are case insensitive. If no algorithm is specified,
The <replaceable>algorithm</replaceable> 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.
</para>
</listitem>

43
bin/dnssec/dnssec-dsfromkey.c
View File

@@ -318,30 +318,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 <verbose level>\n");
fprintf(stderr, " -V: print version information\n");
fprintf(stderr, " -K <directory>: directory in which to find "
"key file or keyset file\n");
fprintf(stderr, " -a algorithm: digest algorithm "
"(SHA-1, SHA-256 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-<dnsname> 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 or SHA-384)\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-<dnsname> 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);
}

243
bin/dnssec/dnssec-dsfromkey.docbook
View File

@@ -49,56 +49,108 @@
<refsynopsisdiv>
<cmdsynopsis sepchar=" ">
<command>dnssec-dsfromkey</command>
<arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-1</option></arg>
<arg choice="opt" rep="norepeat"><option>-2</option></arg>
<arg choice="opt" rep="norepeat"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-C</option></arg>
<arg choice="opt" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
<group choice="opt">
<arg choice="plain"><option>-1</option></arg>
<arg choice="plain"><option>-2</option></arg>
<arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
</group>
<group>
<arg choice="plain" rep="norepeat"><option>-C</option></arg>
<arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
</group>
<arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
<arg choice="req" rep="norepeat">keyfile</arg>
</cmdsynopsis>
<cmdsynopsis sepchar=" ">
<command>dnssec-dsfromkey</command>
<arg choice="req" rep="norepeat">-s</arg>
<arg choice="opt" rep="norepeat"><option>-1</option></arg>
<arg choice="opt" rep="norepeat"><option>-2</option></arg>
<arg choice="opt" rep="norepeat"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-s</option></arg>
<arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
<group choice="opt">
<arg choice="plain"><option>-1</option></arg>
<arg choice="plain"><option>-2</option></arg>
<arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
</group>
<group>
<arg choice="plain" rep="norepeat"><option>-C</option></arg>
<arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
</group>
<arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-f <replaceable class="parameter">file</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-A</option></arg>
<arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
<arg choice="req" rep="norepeat">dnsname</arg>
</cmdsynopsis>
<arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-A</option></arg>
<arg choice="req" rep="norepeat"><option>-f <replaceable class="parameter">file</replaceable></option></arg>
<arg choice="opt" rep="norepeat">dnsname</arg>
</cmdsynopsis>
<cmdsynopsis sepchar=" ">
<command>dnssec-dsfromkey</command>
<arg choice="opt" rep="norepeat"><option>-h</option></arg>
<arg choice="opt" rep="norepeat"><option>-V</option></arg>
</cmdsynopsis>
<group choice="opt">
<arg choice="plain"><option>-1</option></arg>
<arg choice="plain"><option>-2</option></arg>
<arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
</group>
<group>
<arg choice="plain" rep="norepeat"><option>-C</option></arg>
<arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
</group>
<arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
<arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
<arg choice="req" rep="norepeat">-s</arg>
<arg choice="req" rep="norepeat">dnsname</arg>
</cmdsynopsis>
<cmdsynopsis sepchar=" ">
<command>dnssec-dsfromkey</command>
<group choice="opt">
<arg choice="plain" rep="norepeat"><option>-h</option></arg>
<arg choice="plain" rep="norepeat"><option>-V</option></arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsection><info><title>DESCRIPTION</title></info>
<para><command>dnssec-dsfromkey</command>
outputs the Delegation Signer (DS) resource record (RR), as defined in
RFC 3658 and RFC 4509, for the given key(s).
<para>
The <command>dnssec-dsfromkey</command> command outputs DS (Delegation
Signer) resource records (RRs) and other similarly-constructed RRs:
with the <option>-l</option> option it outputs DLV (DNSSEC Lookaside
Validation) RRs; or with the <option>-C</option> it outputs CDS (Child
DS) RRs.
</para>
<para>
The input keys can be specified in a number of ways:
</para>
<para>
By default, <command>dnssec-dsfromkey</command> reads a key file
named like <filename>Knnnn.+aaa+iiiii.key</filename>, as generated
by <command>dnssec-keygen</command>.
</para>
<para>
With the <option>-f <replaceable>file</replaceable></option>
option, <command>dnssec-dsfromkey</command> reads keys from a zone file
or partial zone file (which can contain just the DNSKEY records).
</para>
<para>
With the <option>-s</option>
option, <command>dnssec-dsfromkey</command> reads
a <filename>keyset-</filename> file, as generated
by <command>dnssec-keygen</command> <option>-C</option>.
</para>
</refsection>
<refsection><info><title>OPTIONS</title></info>
<variablelist>
<varlistentry>
<term>-1</term>
<listitem>
<para>
Use SHA-1 as the digest algorithm (the default is to use
both SHA-1 and SHA-256).
An abbreviation for <option>-a SHA1</option>
</para>
</listitem>
</varlistentry>
@@ -107,7 +159,7 @@
<term>-2</term>
<listitem>
<para>
Use SHA-256 as the digest algorithm.
An abbreviation for <option>-a SHA-256</option>
</para>
</listitem>
</varlistentry>
@@ -116,40 +168,49 @@
<term>-a <replaceable class="parameter">algorithm</replaceable></term>
<listitem>
<para>
Select the digest algorithm. The value of
<option>algorithm</option> must be one of SHA-1 (SHA1),
SHA-256 (SHA256) 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.
</para>
<para>
The <replaceable>algorithm</replaceable> 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-A</term>
<listitem>
<para>
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 <option>-f</option> zone file mode.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">class</replaceable></term>
<listitem>
<para>
Specifies the DNS class (default is IN). Useful only
in <option>-s</option> keyset or <option>-f</option>
zone file mode.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-C</term>
<listitem>
<para>
Generate CDS records rather than DS records. This is mutually
exclusive with generating lookaside records.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-T <replaceable class="parameter">TTL</replaceable></term>
<listitem>
<para>
Specifies the TTL of the DS records.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-K <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
Look for key files (or, in keyset mode,
<filename>keyset-</filename> files) in
<option>directory</option>.
Generate CDS records rather than DS records. This is mutually
exclusive with the <option>-l</option> option for generating DLV
records.
</para>
</listitem>
</varlistentry>
@@ -158,13 +219,14 @@
<term>-f <replaceable class="parameter">file</replaceable></term>
<listitem>
<para>
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: <command>dnssec-dsfromkey</command>'s
final <replaceable>dnsname</replaceable> argument is
the DNS domain name of a zone whose master file can be read
from <option>file</option>. If the zone name is the same as
<option>file</option>, then it may be omitted.
</para>
<para>
If <option>file</option> is set to <literal>"-"</literal>, then
If <replaceable>file</replaceable> is <literal>"-"</literal>, then
the zone data is read from the standard input. This makes it
possible to use the output of the <command>dig</command>
command as input, as in:
@@ -176,26 +238,33 @@
</varlistentry>
<varlistentry>
<term>-A</term>
<listitem>
<para>
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.
</para>
</listitem>
<term>-h</term>
<listitem>
<para>
Prints usage information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-K <replaceable class="parameter">directory</replaceable></term>
<listitem>
<para>
Look for key files or <filename>keyset-</filename> files in
<option>directory</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-l <replaceable class="parameter">domain</replaceable></term>
<listitem>
<para>
Generate a DLV set instead of a DS set. The specified
<option>domain</option> is appended to the name for each
Generate a DLV set instead of a DS set. The specified
<replaceable>domain</replaceable> 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.
This is mutually exclusive with the <option>-C</option> option
for generating CDS records.
</para>
</listitem>
</varlistentry>
@@ -204,18 +273,18 @@
<term>-s</term>
<listitem>
<para>
Keyset mode: in place of the keyfile name, the argument is
the DNS domain name of a keyset file.
Keyset mode: <command>dnssec-dsfromkey</command>'s
final <replaceable>dnsname</replaceable> argument is the DNS
domain name used to locate a <filename>keyset-</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">class</replaceable></term>
<term>-T <replaceable class="parameter">TTL</replaceable></term>
<listitem>
<para>
Specifies the DNS class (default is IN). Useful only
in keyset or zone file mode.
Specifies the TTL of the DS records. By default the TTL is omitted.
</para>
</listitem>
</varlistentry>
@@ -229,15 +298,6 @@
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem>
<para>
Prints usage information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-V</term>
<listitem>
@@ -254,21 +314,22 @@
<para>
To build the SHA-256 DS RR from the
<userinput>Kexample.com.+003+26160</userinput>
keyfile name, the following command would be issued:
keyfile name, you can issue the following command:
</para>
<para><userinput>dnssec-dsfromkey -2 Kexample.com.+003+26160</userinput>
</para>
<para>
The command would print something like:
</para>
<para><userinput>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0 C5EA0B94</userinput>
<para><userinput>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94</userinput>
</para>
</refsection>
<refsection><info><title>FILES</title></info>
<para>
The keyfile can be designed by the key identification
The keyfile can be designated by the key identification
<filename>Knnnn.+aaa+iiiii</filename> or the full file name
<filename>Knnnn.+aaa+iiiii.key</filename> as generated by
<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>.
@@ -296,9 +357,11 @@
<refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>,
<citetitle>RFC 3658</citetitle>,
<citetitle>RFC 4431</citetitle>.
<citetitle>RFC 4509</citetitle>.
<citetitle>RFC 3658</citetitle> (DS RRs),
<citetitle>RFC 4431</citetitle> (DLV RRs),
<citetitle>RFC 4509</citetitle> (SHA-256 for DS RRs),
<citetitle>RFC 6605</citetitle> (SHA-384 for DS RRs),
<citetitle>RFC 7344</citetitle> (CDS and CDNSKEY RRs).
</para>
</refsection>