Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-dsfromkey.docbook
CommitLineData
582f8b9a 1<!--
843d3896 2 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
582f8b9a 3 -
0c27b3fe
MA
4 - This Source Code Form is subject to the terms of the Mozilla Public
5 - License, v. 2.0. If a copy of the MPL was not distributed with this
6 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
843d3896
OS
7 -
8 - See the COPYRIGHT file distributed with this work for additional
9 - information regarding copyright ownership.
582f8b9a 10-->
2eeb74d1 11
14a656f9 12<!-- Converted by db4-upgrade version 1.0 -->
1b8ce3b3 13<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.dnssec-dsfromkey">
14a656f9 14 <info>
796a6c4e 15 <date>2019-05-08</date>
14a656f9 16 </info>
582f8b9a 17 <refentryinfo>
14a656f9
EH
18 <corpname>ISC</corpname>
19 <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
582f8b9a
MA
20 </refentryinfo>
21
22 <refmeta>
23 <refentrytitle><application>dnssec-dsfromkey</application></refentrytitle>
24 <manvolnum>8</manvolnum>
25 <refmiscinfo>BIND9</refmiscinfo>
26 </refmeta>
27
28 <refnamediv>
29 <refname><application>dnssec-dsfromkey</application></refname>
30 <refpurpose>DNSSEC DS RR generation tool</refpurpose>
31 </refnamediv>
32
33 <docinfo>
34 <copyright>
35 <year>2008</year>
dde86591 36 <year>2009</year>
a094c466 37 <year>2010</year>
06140f73 38 <year>2011</year>
99d8f5a7 39 <year>2012</year>
93844069 40 <year>2014</year>
431e5c81 41 <year>2015</year>
0c27b3fe 42 <year>2016</year>
843d3896 43 <year>2018</year>
dc64b706 44 <year>2019</year>
582f8b9a
MA
45 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
46 </copyright>
47 </docinfo>
48
49 <refsynopsisdiv>
14a656f9 50 <cmdsynopsis sepchar=" ">
582f8b9a 51 <command>dnssec-dsfromkey</command>
6ca8e130
TF
52 <group choice="opt">
53 <arg choice="plain"><option>-1</option></arg>
54 <arg choice="plain"><option>-2</option></arg>
55 <arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
56 </group>
57 <group>
58 <arg choice="plain" rep="norepeat"><option>-C</option></arg>
59 <arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
60 </group>
14a656f9 61 <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
6ca8e130
TF
62 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
63 <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
14a656f9 64 <arg choice="req" rep="norepeat">keyfile</arg>
582f8b9a 65 </cmdsynopsis>
14a656f9 66 <cmdsynopsis sepchar=" ">
582f8b9a 67 <command>dnssec-dsfromkey</command>
6ca8e130
TF
68 <group choice="opt">
69 <arg choice="plain"><option>-1</option></arg>
70 <arg choice="plain"><option>-2</option></arg>
71 <arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
72 </group>
73 <group>
74 <arg choice="plain" rep="norepeat"><option>-C</option></arg>
75 <arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
76 </group>
14a656f9 77 <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
6ca8e130
TF
78 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
79 <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
14a656f9 80 <arg choice="opt" rep="norepeat"><option>-A</option></arg>
6ca8e130
TF
81 <arg choice="req" rep="norepeat"><option>-f <replaceable class="parameter">file</replaceable></option></arg>
82 <arg choice="opt" rep="norepeat">dnsname</arg>
83 </cmdsynopsis>
84 <cmdsynopsis sepchar=" ">
85 <command>dnssec-dsfromkey</command>
86 <group choice="opt">
87 <arg choice="plain"><option>-1</option></arg>
88 <arg choice="plain"><option>-2</option></arg>
89 <arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
90 </group>
91 <group>
92 <arg choice="plain" rep="norepeat"><option>-C</option></arg>
93 <arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
94 </group>
95 <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
14a656f9 96 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
6ca8e130
TF
97 <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
98 <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
99 <arg choice="req" rep="norepeat">-s</arg>
14a656f9 100 <arg choice="req" rep="norepeat">dnsname</arg>
6ca8e130 101 </cmdsynopsis>
14a656f9 102 <cmdsynopsis sepchar=" ">
42782931 103 <command>dnssec-dsfromkey</command>
6ca8e130
TF
104 <group choice="opt">
105 <arg choice="plain" rep="norepeat"><option>-h</option></arg>
106 <arg choice="plain" rep="norepeat"><option>-V</option></arg>
107 </group>
108 </cmdsynopsis>
582f8b9a
MA
109 </refsynopsisdiv>
110
14a656f9 111 <refsection><info><title>DESCRIPTION</title></info>
30eec077 112
6ca8e130
TF
113 <para>
114 The <command>dnssec-dsfromkey</command> command outputs DS (Delegation
115 Signer) resource records (RRs) and other similarly-constructed RRs:
116 with the <option>-l</option> option it outputs DLV (DNSSEC Lookaside
117 Validation) RRs; or with the <option>-C</option> it outputs CDS (Child
118 DS) RRs.
119 </para>
120
121 <para>
122 The input keys can be specified in a number of ways:
582f8b9a 123 </para>
6ca8e130
TF
124
125 <para>
126 By default, <command>dnssec-dsfromkey</command> reads a key file
127 named like <filename>Knnnn.+aaa+iiiii.key</filename>, as generated
128 by <command>dnssec-keygen</command>.
129 </para>
130
131 <para>
132 With the <option>-f <replaceable>file</replaceable></option>
133 option, <command>dnssec-dsfromkey</command> reads keys from a zone file
134 or partial zone file (which can contain just the DNSKEY records).
135 </para>
136
137 <para>
138 With the <option>-s</option>
139 option, <command>dnssec-dsfromkey</command> reads
140 a <filename>keyset-</filename> file, as generated
141 by <command>dnssec-keygen</command> <option>-C</option>.
142 </para>
143
14a656f9 144 </refsection>
582f8b9a 145
14a656f9 146 <refsection><info><title>OPTIONS</title></info>
30eec077 147
582f8b9a
MA
148 <variablelist>
149 <varlistentry>
e939674d
MA
150 <term>-1</term>
151 <listitem>
152 <para>
796a6c4e
TF
153 An abbreviation for <option>-a SHA-1</option>.
154 (Note: The SHA-1 algorithm is no longer recommended for use
155 when generating new DS and CDS records.)
e939674d
MA
156 </para>
157 </listitem>
582f8b9a
MA
158 </varlistentry>
159
160 <varlistentry>
e939674d
MA
161 <term>-2</term>
162 <listitem>
163 <para>
796a6c4e 164 An abbreviation for <option>-a SHA-256</option>.
e939674d
MA
165 </para>
166 </listitem>
582f8b9a
MA
167 </varlistentry>
168
169 <varlistentry>
e939674d
MA
170 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
171 <listitem>
172 <para>
6ca8e130
TF
173 Specify a digest algorithm to use when converting DNSKEY
174 records to DS records. This option can be repeated, so
175 that multiple DS records are created for each DNSKEY
176 record.
177 </para>
178 <para>
179 The <replaceable>algorithm</replaceable> must be one of
180 SHA-1, SHA-256, or SHA-384. These values are case insensitive,
181 and the hyphen may be omitted. If no algorithm is specified,
182 the default is SHA-256.
796a6c4e
TF
183 (Note: The SHA-1 algorithm is no longer recommended for use
184 when generating new DS and CDS records.)
e939674d
MA
185 </para>
186 </listitem>
582f8b9a
MA
187 </varlistentry>
188
598b5026 189 <varlistentry>
6ca8e130
TF
190 <term>-A</term>
191 <listitem>
192 <para>
193 Include ZSKs when generating DS records. Without this option, only
194 keys which have the KSK flag set will be converted to DS records
195 and printed. Useful only in <option>-f</option> zone file mode.
196 </para>
197 </listitem>
598b5026
MA
198 </varlistentry>
199
b1c6de54 200 <varlistentry>
6ca8e130 201 <term>-c <replaceable class="parameter">class</replaceable></term>
e939674d
MA
202 <listitem>
203 <para>
6ca8e130
TF
204 Specifies the DNS class (default is IN). Useful only
205 in <option>-s</option> keyset or <option>-f</option>
206 zone file mode.
e939674d 207 </para>
b1c6de54
MA
208 </listitem>
209 </varlistentry>
210
582f8b9a 211 <varlistentry>
6ca8e130 212 <term>-C</term>
e939674d
MA
213 <listitem>
214 <para>
6ca8e130
TF
215 Generate CDS records rather than DS records. This is mutually
216 exclusive with the <option>-l</option> option for generating DLV
217 records.
e939674d
MA
218 </para>
219 </listitem>
553ead32
EH
220 </varlistentry>
221
222 <varlistentry>
e939674d
MA
223 <term>-f <replaceable class="parameter">file</replaceable></term>
224 <listitem>
225 <para>
6ca8e130
TF
226 Zone file mode: <command>dnssec-dsfromkey</command>'s
227 final <replaceable>dnsname</replaceable> argument is
228 the DNS domain name of a zone whose master file can be read
e939674d
MA
229 from <option>file</option>. If the zone name is the same as
230 <option>file</option>, then it may be omitted.
231 </para>
232 <para>
6ca8e130 233 If <replaceable>file</replaceable> is <literal>"-"</literal>, then
e939674d
MA
234 the zone data is read from the standard input. This makes it
235 possible to use the output of the <command>dig</command>
236 command as input, as in:
237 </para>
238 <para>
239 <userinput>dig dnskey example.com | dnssec-dsfromkey -f - example.com</userinput>
240 </para>
241 </listitem>
553ead32
EH
242 </varlistentry>
243
244 <varlistentry>
6ca8e130
TF
245 <term>-h</term>
246 <listitem>
247 <para>
248 Prints usage information.
249 </para>
250 </listitem>
582f8b9a
MA
251 </varlistentry>
252
b272d38c 253 <varlistentry>
6ca8e130 254 <term>-K <replaceable class="parameter">directory</replaceable></term>
e939674d
MA
255 <listitem>
256 <para>
6ca8e130
TF
257 Look for key files or <filename>keyset-</filename> files in
258 <option>directory</option>.
e939674d
MA
259 </para>
260 </listitem>
b272d38c
EH
261 </varlistentry>
262
582f8b9a 263 <varlistentry>
6ca8e130 264 <term>-l <replaceable class="parameter">domain</replaceable></term>
e939674d
MA
265 <listitem>
266 <para>
6ca8e130
TF
267 Generate a DLV set instead of a DS set. The specified
268 <replaceable>domain</replaceable> is appended to the name for each
269 record in the set.
270 This is mutually exclusive with the <option>-C</option> option
271 for generating CDS records.
e939674d
MA
272 </para>
273 </listitem>
582f8b9a
MA
274 </varlistentry>
275
276 <varlistentry>
6ca8e130 277 <term>-s</term>
e939674d
MA
278 <listitem>
279 <para>
6ca8e130
TF
280 Keyset mode: <command>dnssec-dsfromkey</command>'s
281 final <replaceable>dnsname</replaceable> argument is the DNS
282 domain name used to locate a <filename>keyset-</filename> file.
e939674d 283 </para>
6ca8e130 284 </listitem>
582f8b9a
MA
285 </varlistentry>
286
287 <varlistentry>
6ca8e130 288 <term>-T <replaceable class="parameter">TTL</replaceable></term>
e939674d
MA
289 <listitem>
290 <para>
6ca8e130 291 Specifies the TTL of the DS records. By default the TTL is omitted.
e939674d 292 </para>
6ca8e130 293 </listitem>
582f8b9a 294 </varlistentry>
42782931
MS
295
296 <varlistentry>
6ca8e130 297 <term>-v <replaceable class="parameter">level</replaceable></term>
e939674d
MA
298 <listitem>
299 <para>
6ca8e130 300 Sets the debugging level.
e939674d
MA
301 </para>
302 </listitem>
42782931
MS
303 </varlistentry>
304
305 <varlistentry>
e939674d
MA
306 <term>-V</term>
307 <listitem>
308 <para>
309 Prints version information.
310 </para>
311 </listitem>
42782931 312 </varlistentry>
582f8b9a 313 </variablelist>
14a656f9 314 </refsection>
582f8b9a 315
14a656f9 316 <refsection><info><title>EXAMPLE</title></info>
30eec077 317
582f8b9a
MA
318 <para>
319 To build the SHA-256 DS RR from the
320 <userinput>Kexample.com.+003+26160</userinput>
6ca8e130 321 keyfile name, you can issue the following command:
582f8b9a
MA
322 </para>
323 <para><userinput>dnssec-dsfromkey -2 Kexample.com.+003+26160</userinput>
324 </para>
325 <para>
326 The command would print something like:
327 </para>
6ca8e130 328 <para><userinput>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94</userinput>
582f8b9a 329 </para>
6ca8e130 330
14a656f9 331 </refsection>
582f8b9a 332
14a656f9 333 <refsection><info><title>FILES</title></info>
30eec077 334
582f8b9a 335 <para>
6ca8e130 336 The keyfile can be designated by the key identification
582f8b9a 337 <filename>Knnnn.+aaa+iiiii</filename> or the full file name
832fb12c 338 <filename>Knnnn.+aaa+iiiii.key</filename> as generated by
582f8b9a
MA
339 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>.
340 </para>
341 <para>
342 The keyset file name is built from the <option>directory</option>,
343 the string <filename>keyset-</filename> and the
344 <option>dnsname</option>.
345 </para>
14a656f9 346 </refsection>
582f8b9a 347
14a656f9 348 <refsection><info><title>CAVEAT</title></info>
30eec077 349
582f8b9a
MA
350 <para>
351 A keyfile error can give a "file not found" even if the file exists.
352 </para>
14a656f9 353 </refsection>
582f8b9a 354
14a656f9 355 <refsection><info><title>SEE ALSO</title></info>
30eec077 356
582f8b9a 357 <para><citerefentry>
e939674d 358 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
582f8b9a
MA
359 </citerefentry>,
360 <citerefentry>
e939674d 361 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
582f8b9a
MA
362 </citerefentry>,
363 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
6ca8e130
TF
364 <citetitle>RFC 3658</citetitle> (DS RRs),
365 <citetitle>RFC 4431</citetitle> (DLV RRs),
366 <citetitle>RFC 4509</citetitle> (SHA-256 for DS RRs),
367 <citetitle>RFC 6605</citetitle> (SHA-384 for DS RRs),
368 <citetitle>RFC 7344</citetitle> (CDS and CDNSKEY RRs).
582f8b9a 369 </para>
14a656f9 370 </refsection>
582f8b9a 371
14a656f9 372</refentry>