Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-dsfromkey.docbook
1 <!--
2 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3 -
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/.
7 -
8 - See the COPYRIGHT file distributed with this work for additional
9 - information regarding copyright ownership.
10 -->
11
12 <!-- Converted by db4-upgrade version 1.0 -->
13 <refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.dnssec-dsfromkey">
14 <info>
15 <date>2019-05-08</date>
16 </info>
17 <refentryinfo>
18 <corpname>ISC</corpname>
19 <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
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>
36 <year>2009</year>
37 <year>2010</year>
38 <year>2011</year>
39 <year>2012</year>
40 <year>2014</year>
41 <year>2015</year>
42 <year>2016</year>
43 <year>2018</year>
44 <year>2019</year>
45 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
46 </copyright>
47 </docinfo>
48
49 <refsynopsisdiv>
50 <cmdsynopsis sepchar=" ">
51 <command>dnssec-dsfromkey</command>
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>
61 <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
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>
64 <arg choice="req" rep="norepeat">keyfile</arg>
65 </cmdsynopsis>
66 <cmdsynopsis sepchar=" ">
67 <command>dnssec-dsfromkey</command>
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>
77 <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
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>
80 <arg choice="opt" rep="norepeat"><option>-A</option></arg>
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>
96 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
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>
100 <arg choice="req" rep="norepeat">dnsname</arg>
101 </cmdsynopsis>
102 <cmdsynopsis sepchar=" ">
103 <command>dnssec-dsfromkey</command>
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>
109 </refsynopsisdiv>
110
111 <refsection><info><title>DESCRIPTION</title></info>
112
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:
123 </para>
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
144 </refsection>
145
146 <refsection><info><title>OPTIONS</title></info>
147
148 <variablelist>
149 <varlistentry>
150 <term>-1</term>
151 <listitem>
152 <para>
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.)
156 </para>
157 </listitem>
158 </varlistentry>
159
160 <varlistentry>
161 <term>-2</term>
162 <listitem>
163 <para>
164 An abbreviation for <option>-a SHA-256</option>.
165 </para>
166 </listitem>
167 </varlistentry>
168
169 <varlistentry>
170 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
171 <listitem>
172 <para>
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.
183 (Note: The SHA-1 algorithm is no longer recommended for use
184 when generating new DS and CDS records.)
185 </para>
186 </listitem>
187 </varlistentry>
188
189 <varlistentry>
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>
198 </varlistentry>
199
200 <varlistentry>
201 <term>-c <replaceable class="parameter">class</replaceable></term>
202 <listitem>
203 <para>
204 Specifies the DNS class (default is IN). Useful only
205 in <option>-s</option> keyset or <option>-f</option>
206 zone file mode.
207 </para>
208 </listitem>
209 </varlistentry>
210
211 <varlistentry>
212 <term>-C</term>
213 <listitem>
214 <para>
215 Generate CDS records rather than DS records. This is mutually
216 exclusive with the <option>-l</option> option for generating DLV
217 records.
218 </para>
219 </listitem>
220 </varlistentry>
221
222 <varlistentry>
223 <term>-f <replaceable class="parameter">file</replaceable></term>
224 <listitem>
225 <para>
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
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>
233 If <replaceable>file</replaceable> is <literal>"-"</literal>, then
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>
242 </varlistentry>
243
244 <varlistentry>
245 <term>-h</term>
246 <listitem>
247 <para>
248 Prints usage information.
249 </para>
250 </listitem>
251 </varlistentry>
252
253 <varlistentry>
254 <term>-K <replaceable class="parameter">directory</replaceable></term>
255 <listitem>
256 <para>
257 Look for key files or <filename>keyset-</filename> files in
258 <option>directory</option>.
259 </para>
260 </listitem>
261 </varlistentry>
262
263 <varlistentry>
264 <term>-l <replaceable class="parameter">domain</replaceable></term>
265 <listitem>
266 <para>
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.
272 </para>
273 </listitem>
274 </varlistentry>
275
276 <varlistentry>
277 <term>-s</term>
278 <listitem>
279 <para>
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.
283 </para>
284 </listitem>
285 </varlistentry>
286
287 <varlistentry>
288 <term>-T <replaceable class="parameter">TTL</replaceable></term>
289 <listitem>
290 <para>
291 Specifies the TTL of the DS records. By default the TTL is omitted.
292 </para>
293 </listitem>
294 </varlistentry>
295
296 <varlistentry>
297 <term>-v <replaceable class="parameter">level</replaceable></term>
298 <listitem>
299 <para>
300 Sets the debugging level.
301 </para>
302 </listitem>
303 </varlistentry>
304
305 <varlistentry>
306 <term>-V</term>
307 <listitem>
308 <para>
309 Prints version information.
310 </para>
311 </listitem>
312 </varlistentry>
313 </variablelist>
314 </refsection>
315
316 <refsection><info><title>EXAMPLE</title></info>
317
318 <para>
319 To build the SHA-256 DS RR from the
320 <userinput>Kexample.com.+003+26160</userinput>
321 keyfile name, you can issue the following command:
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>
328 <para><userinput>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94</userinput>
329 </para>
330
331 </refsection>
332
333 <refsection><info><title>FILES</title></info>
334
335 <para>
336 The keyfile can be designated by the key identification
337 <filename>Knnnn.+aaa+iiiii</filename> or the full file name
338 <filename>Knnnn.+aaa+iiiii.key</filename> as generated by
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>
346 </refsection>
347
348 <refsection><info><title>CAVEAT</title></info>
349
350 <para>
351 A keyfile error can give a "file not found" even if the file exists.
352 </para>
353 </refsection>
354
355 <refsection><info><title>SEE ALSO</title></info>
356
357 <para><citerefentry>
358 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
359 </citerefentry>,
360 <citerefentry>
361 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
362 </citerefentry>,
363 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
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).
369 </para>
370 </refsection>
371
372 </refentry>