Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_13_...
[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
EH
14 <info>
15 <date>2012-05-02</date>
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>
6ca8e130 153 An abbreviation for <option>-a SHA1</option>
e939674d
MA
154 </para>
155 </listitem>
582f8b9a
MA
156 </varlistentry>
157
158 <varlistentry>
e939674d
MA
159 <term>-2</term>
160 <listitem>
161 <para>
6ca8e130 162 An abbreviation for <option>-a SHA-256</option>
e939674d
MA
163 </para>
164 </listitem>
582f8b9a
MA
165 </varlistentry>
166
167 <varlistentry>
e939674d
MA
168 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
169 <listitem>
170 <para>
6ca8e130
TF
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.
e939674d
MA
181 </para>
182 </listitem>
582f8b9a
MA
183 </varlistentry>
184
598b5026 185 <varlistentry>
6ca8e130
TF
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>
598b5026
MA
194 </varlistentry>
195
b1c6de54 196 <varlistentry>
6ca8e130 197 <term>-c <replaceable class="parameter">class</replaceable></term>
e939674d
MA
198 <listitem>
199 <para>
6ca8e130
TF
200 Specifies the DNS class (default is IN). Useful only
201 in <option>-s</option> keyset or <option>-f</option>
202 zone file mode.
e939674d 203 </para>
b1c6de54
MA
204 </listitem>
205 </varlistentry>
206
582f8b9a 207 <varlistentry>
6ca8e130 208 <term>-C</term>
e939674d
MA
209 <listitem>
210 <para>
6ca8e130
TF
211 Generate CDS records rather than DS records. This is mutually
212 exclusive with the <option>-l</option> option for generating DLV
213 records.
e939674d
MA
214 </para>
215 </listitem>
553ead32
EH
216 </varlistentry>
217
218 <varlistentry>
e939674d
MA
219 <term>-f <replaceable class="parameter">file</replaceable></term>
220 <listitem>
221 <para>
6ca8e130
TF
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
e939674d
MA
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>
6ca8e130 229 If <replaceable>file</replaceable> is <literal>"-"</literal>, then
e939674d
MA
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>
553ead32
EH
238 </varlistentry>
239
240 <varlistentry>
6ca8e130
TF
241 <term>-h</term>
242 <listitem>
243 <para>
244 Prints usage information.
245 </para>
246 </listitem>
582f8b9a
MA
247 </varlistentry>
248
b272d38c 249 <varlistentry>
6ca8e130 250 <term>-K <replaceable class="parameter">directory</replaceable></term>
e939674d
MA
251 <listitem>
252 <para>
6ca8e130
TF
253 Look for key files or <filename>keyset-</filename> files in
254 <option>directory</option>.
e939674d
MA
255 </para>
256 </listitem>
b272d38c
EH
257 </varlistentry>
258
582f8b9a 259 <varlistentry>
6ca8e130 260 <term>-l <replaceable class="parameter">domain</replaceable></term>
e939674d
MA
261 <listitem>
262 <para>
6ca8e130
TF
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.
e939674d
MA
268 </para>
269 </listitem>
582f8b9a
MA
270 </varlistentry>
271
272 <varlistentry>
6ca8e130 273 <term>-s</term>
e939674d
MA
274 <listitem>
275 <para>
6ca8e130
TF
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.
e939674d 279 </para>
6ca8e130 280 </listitem>
582f8b9a
MA
281 </varlistentry>
282
283 <varlistentry>
6ca8e130 284 <term>-T <replaceable class="parameter">TTL</replaceable></term>
e939674d
MA
285 <listitem>
286 <para>
6ca8e130 287 Specifies the TTL of the DS records. By default the TTL is omitted.
e939674d 288 </para>
6ca8e130 289 </listitem>
582f8b9a 290 </varlistentry>
42782931
MS
291
292 <varlistentry>
6ca8e130 293 <term>-v <replaceable class="parameter">level</replaceable></term>
e939674d
MA
294 <listitem>
295 <para>
6ca8e130 296 Sets the debugging level.
e939674d
MA
297 </para>
298 </listitem>
42782931
MS
299 </varlistentry>
300
301 <varlistentry>
e939674d
MA
302 <term>-V</term>
303 <listitem>
304 <para>
305 Prints version information.
306 </para>
307 </listitem>
42782931 308 </varlistentry>
582f8b9a 309 </variablelist>
14a656f9 310 </refsection>
582f8b9a 311
14a656f9 312 <refsection><info><title>EXAMPLE</title></info>
30eec077 313
582f8b9a
MA
314 <para>
315 To build the SHA-256 DS RR from the
316 <userinput>Kexample.com.+003+26160</userinput>
6ca8e130 317 keyfile name, you can issue the following command:
582f8b9a
MA
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>
6ca8e130 324 <para><userinput>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94</userinput>
582f8b9a 325 </para>
6ca8e130 326
14a656f9 327 </refsection>
582f8b9a 328
14a656f9 329 <refsection><info><title>FILES</title></info>
30eec077 330
582f8b9a 331 <para>
6ca8e130 332 The keyfile can be designated by the key identification
582f8b9a 333 <filename>Knnnn.+aaa+iiiii</filename> or the full file name
832fb12c 334 <filename>Knnnn.+aaa+iiiii.key</filename> as generated by
582f8b9a
MA
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>
14a656f9 342 </refsection>
582f8b9a 343
14a656f9 344 <refsection><info><title>CAVEAT</title></info>
30eec077 345
582f8b9a
MA
346 <para>
347 A keyfile error can give a "file not found" even if the file exists.
348 </para>
14a656f9 349 </refsection>
582f8b9a 350
14a656f9 351 <refsection><info><title>SEE ALSO</title></info>
30eec077 352
582f8b9a 353 <para><citerefentry>
e939674d 354 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
582f8b9a
MA
355 </citerefentry>,
356 <citerefentry>
e939674d 357 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
582f8b9a
MA
358 </citerefentry>,
359 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
6ca8e130
TF
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).
582f8b9a 365 </para>
14a656f9 366 </refsection>
582f8b9a 367
14a656f9 368</refentry>