Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_13_...
[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>2012-05-02</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 SHA1</option>
154 </para>
155 </listitem>
156 </varlistentry>
157
158 <varlistentry>
159 <term>-2</term>
160 <listitem>
161 <para>
162 An abbreviation for <option>-a SHA-256</option>
163 </para>
164 </listitem>
165 </varlistentry>
166
167 <varlistentry>
168 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
169 <listitem>
170 <para>
171 Specify a digest algorithm to use when converting DNSKEY
172 records to DS records. This option can be repeated, so
173 that multiple DS records are created for each DNSKEY
174 record.
175 </para>
176 <para>
177 The <replaceable>algorithm</replaceable> must be one of
178 SHA-1, SHA-256, or SHA-384. These values are case insensitive,
179 and the hyphen may be omitted. If no algorithm is specified,
180 the default is SHA-256.
181 </para>
182 </listitem>
183 </varlistentry>
184
185 <varlistentry>
186 <term>-A</term>
187 <listitem>
188 <para>
189 Include ZSKs when generating DS records. Without this option, only
190 keys which have the KSK flag set will be converted to DS records
191 and printed. Useful only in <option>-f</option> zone file mode.
192 </para>
193 </listitem>
194 </varlistentry>
195
196 <varlistentry>
197 <term>-c <replaceable class="parameter">class</replaceable></term>
198 <listitem>
199 <para>
200 Specifies the DNS class (default is IN). Useful only
201 in <option>-s</option> keyset or <option>-f</option>
202 zone file mode.
203 </para>
204 </listitem>
205 </varlistentry>
206
207 <varlistentry>
208 <term>-C</term>
209 <listitem>
210 <para>
211 Generate CDS records rather than DS records. This is mutually
212 exclusive with the <option>-l</option> option for generating DLV
213 records.
214 </para>
215 </listitem>
216 </varlistentry>
217
218 <varlistentry>
219 <term>-f <replaceable class="parameter">file</replaceable></term>
220 <listitem>
221 <para>
222 Zone file mode: <command>dnssec-dsfromkey</command>'s
223 final <replaceable>dnsname</replaceable> argument is
224 the DNS domain name of a zone whose master file can be read
225 from <option>file</option>. If the zone name is the same as
226 <option>file</option>, then it may be omitted.
227 </para>
228 <para>
229 If <replaceable>file</replaceable> is <literal>"-"</literal>, then
230 the zone data is read from the standard input. This makes it
231 possible to use the output of the <command>dig</command>
232 command as input, as in:
233 </para>
234 <para>
235 <userinput>dig dnskey example.com | dnssec-dsfromkey -f - example.com</userinput>
236 </para>
237 </listitem>
238 </varlistentry>
239
240 <varlistentry>
241 <term>-h</term>
242 <listitem>
243 <para>
244 Prints usage information.
245 </para>
246 </listitem>
247 </varlistentry>
248
249 <varlistentry>
250 <term>-K <replaceable class="parameter">directory</replaceable></term>
251 <listitem>
252 <para>
253 Look for key files or <filename>keyset-</filename> files in
254 <option>directory</option>.
255 </para>
256 </listitem>
257 </varlistentry>
258
259 <varlistentry>
260 <term>-l <replaceable class="parameter">domain</replaceable></term>
261 <listitem>
262 <para>
263 Generate a DLV set instead of a DS set. The specified
264 <replaceable>domain</replaceable> is appended to the name for each
265 record in the set.
266 This is mutually exclusive with the <option>-C</option> option
267 for generating CDS records.
268 </para>
269 </listitem>
270 </varlistentry>
271
272 <varlistentry>
273 <term>-s</term>
274 <listitem>
275 <para>
276 Keyset mode: <command>dnssec-dsfromkey</command>'s
277 final <replaceable>dnsname</replaceable> argument is the DNS
278 domain name used to locate a <filename>keyset-</filename> file.
279 </para>
280 </listitem>
281 </varlistentry>
282
283 <varlistentry>
284 <term>-T <replaceable class="parameter">TTL</replaceable></term>
285 <listitem>
286 <para>
287 Specifies the TTL of the DS records. By default the TTL is omitted.
288 </para>
289 </listitem>
290 </varlistentry>
291
292 <varlistentry>
293 <term>-v <replaceable class="parameter">level</replaceable></term>
294 <listitem>
295 <para>
296 Sets the debugging level.
297 </para>
298 </listitem>
299 </varlistentry>
300
301 <varlistentry>
302 <term>-V</term>
303 <listitem>
304 <para>
305 Prints version information.
306 </para>
307 </listitem>
308 </varlistentry>
309 </variablelist>
310 </refsection>
311
312 <refsection><info><title>EXAMPLE</title></info>
313
314 <para>
315 To build the SHA-256 DS RR from the
316 <userinput>Kexample.com.+003+26160</userinput>
317 keyfile name, you can issue the following command:
318 </para>
319 <para><userinput>dnssec-dsfromkey -2 Kexample.com.+003+26160</userinput>
320 </para>
321 <para>
322 The command would print something like:
323 </para>
324 <para><userinput>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94</userinput>
325 </para>
326
327 </refsection>
328
329 <refsection><info><title>FILES</title></info>
330
331 <para>
332 The keyfile can be designated by the key identification
333 <filename>Knnnn.+aaa+iiiii</filename> or the full file name
334 <filename>Knnnn.+aaa+iiiii.key</filename> as generated by
335 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>.
336 </para>
337 <para>
338 The keyset file name is built from the <option>directory</option>,
339 the string <filename>keyset-</filename> and the
340 <option>dnsname</option>.
341 </para>
342 </refsection>
343
344 <refsection><info><title>CAVEAT</title></info>
345
346 <para>
347 A keyfile error can give a "file not found" even if the file exists.
348 </para>
349 </refsection>
350
351 <refsection><info><title>SEE ALSO</title></info>
352
353 <para><citerefentry>
354 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
355 </citerefentry>,
356 <citerefentry>
357 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
358 </citerefentry>,
359 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
360 <citetitle>RFC 3658</citetitle> (DS RRs),
361 <citetitle>RFC 4431</citetitle> (DLV RRs),
362 <citetitle>RFC 4509</citetitle> (SHA-256 for DS RRs),
363 <citetitle>RFC 6605</citetitle> (SHA-384 for DS RRs),
364 <citetitle>RFC 7344</citetitle> (CDS and CDNSKEY RRs).
365 </para>
366 </refsection>
367
368 </refentry>