Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-keyfromlabel.docbook
CommitLineData
2a31bd53 1<!--
843d3896 2 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
2a31bd53 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.
2a31bd53 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-keyfromlabel">
14a656f9
EH
14 <info>
15 <date>2014-02-27</date>
16 </info>
2a31bd53 17 <refentryinfo>
e939674d 18 <date>August 27, 2015</date>
14a656f9
EH
19 <corpname>ISC</corpname>
20 <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
2a31bd53
FD
21 </refentryinfo>
22
23 <refmeta>
24 <refentrytitle><application>dnssec-keyfromlabel</application></refentrytitle>
25 <manvolnum>8</manvolnum>
26 <refmiscinfo>BIND9</refmiscinfo>
27 </refmeta>
28
29 <refnamediv>
30 <refname><application>dnssec-keyfromlabel</application></refname>
31 <refpurpose>DNSSEC key generation tool</refpurpose>
32 </refnamediv>
33
34 <docinfo>
35 <copyright>
2a31bd53 36 <year>2008</year>
26d8ffe7 37 <year>2009</year>
ca4e44eb 38 <year>2010</year>
784a904b 39 <year>2011</year>
99d8f5a7 40 <year>2012</year>
6ea23853 41 <year>2014</year>
19c7b1a0 42 <year>2015</year>
0c27b3fe 43 <year>2016</year>
b74e1c3b 44 <year>2017</year>
843d3896 45 <year>2018</year>
dc64b706 46 <year>2019</year>
2a31bd53
FD
47 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
48 </copyright>
2a31bd53
FD
49 </docinfo>
50
51 <refsynopsisdiv>
14a656f9 52 <cmdsynopsis sepchar=" ">
2a31bd53 53 <command>dnssec-keyfromlabel</command>
14a656f9
EH
54 <arg choice="req" rep="norepeat">-l <replaceable class="parameter">label</replaceable></arg>
55 <arg choice="opt" rep="norepeat"><option>-3</option></arg>
56 <arg choice="opt" rep="norepeat"><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
57 <arg choice="opt" rep="norepeat"><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
58 <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
59 <arg choice="opt" rep="norepeat"><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
e939674d 60 <arg choice="opt" rep="norepeat"><option>-D sync <replaceable class="parameter">date/offset</replaceable></option></arg>
14a656f9
EH
61 <arg choice="opt" rep="norepeat"><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
62 <arg choice="opt" rep="norepeat"><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
63 <arg choice="opt" rep="norepeat"><option>-G</option></arg>
64 <arg choice="opt" rep="norepeat"><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
65 <arg choice="opt" rep="norepeat"><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
66 <arg choice="opt" rep="norepeat"><option>-k</option></arg>
67 <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
68 <arg choice="opt" rep="norepeat"><option>-L <replaceable class="parameter">ttl</replaceable></option></arg>
69 <arg choice="opt" rep="norepeat"><option>-n <replaceable class="parameter">nametype</replaceable></option></arg>
70 <arg choice="opt" rep="norepeat"><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
e939674d 71 <arg choice="opt" rep="norepeat"><option>-P sync <replaceable class="parameter">date/offset</replaceable></option></arg>
14a656f9
EH
72 <arg choice="opt" rep="norepeat"><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
73 <arg choice="opt" rep="norepeat"><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
74 <arg choice="opt" rep="norepeat"><option>-S <replaceable class="parameter">key</replaceable></option></arg>
75 <arg choice="opt" rep="norepeat"><option>-t <replaceable class="parameter">type</replaceable></option></arg>
76 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
77 <arg choice="opt" rep="norepeat"><option>-V</option></arg>
78 <arg choice="opt" rep="norepeat"><option>-y</option></arg>
79 <arg choice="req" rep="norepeat">name</arg>
2a31bd53
FD
80 </cmdsynopsis>
81 </refsynopsisdiv>
82
14a656f9 83 <refsection><info><title>DESCRIPTION</title></info>
30eec077 84
2a31bd53 85 <para><command>dnssec-keyfromlabel</command>
a60bf97f
EH
86 generates a key pair of files that referencing a key object stored
87 in a cryptographic hardware service module (HSM). The private key
88 file can be used for DNSSEC signing of zone data as if it were a
89 conventional signing key created by <command>dnssec-keygen</command>,
90 but the key material is stored within the HSM, and the actual signing
91 takes place there.
2a31bd53 92 </para>
1f821c10
FD
93 <para>
94 The <option>name</option> of the key is specified on the command
95 line. This must match the name of the zone for which the key is
96 being generated.
97 </para>
14a656f9 98 </refsection>
2a31bd53 99
14a656f9 100 <refsection><info><title>OPTIONS</title></info>
30eec077 101
2a31bd53
FD
102
103 <variablelist>
104 <varlistentry>
e939674d
MA
105 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
106 <listitem>
2a31bd53
FD
107 <para>
108 Selects the cryptographic algorithm. The value of
e69dc0db 109 <option>algorithm</option> must be one of RSASHA1,
d6c50674 110 NSEC3RSASHA1, RSASHA256, RSASHA512,
9b9182fe 111 ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448.
2a31bd53 112 </para>
e939674d
MA
113 <para>
114 If no algorithm is specified, then RSASHA1 will be used by
115 default, unless the <option>-3</option> option is specified,
116 in which case NSEC3RSASHA1 will be used instead. (If
117 <option>-3</option> is used and an algorithm is specified,
118 that algorithm will be checked for compatibility with NSEC3.)
119 </para>
120 <para>
45afdb26
EH
121 These values are case insensitive. In some cases, abbreviations
122 are supported, such as ECDSA256 for ECDSAP256SHA256 and
d6c50674 123 ECDSA384 for ECDSAP384SHA384. If RSASHA1 is specified
45afdb26 124 along with the <option>-3</option> option, then NSEC3RSASHA1
d6c50674 125 will be used instead.
e939674d
MA
126 </para>
127 <para>
45afdb26
EH
128 As of BIND 9.12.0, this option is mandatory except when using
129 the <option>-S</option> option (which copies the algorithm from
130 the predecessory key). Previously, the default for newly
131 generated keys was RSASHA1.
e939674d
MA
132 </para>
133 </listitem>
2a31bd53
FD
134 </varlistentry>
135
d1f39121 136 <varlistentry>
e939674d
MA
137 <term>-3</term>
138 <listitem>
139 <para>
d1f39121 140 Use an NSEC3-capable algorithm to generate a DNSSEC key.
45afdb26
EH
141 If this option is used with an algorithm that has both
142 NSEC and NSEC3 versions, then the NSEC3 version will be
143 used; for example, <command>dnssec-keygen -3a RSASHA1</command>
144 specifies the NSEC3RSASHA1 algorithm.
e939674d
MA
145 </para>
146 </listitem>
d1f39121
EH
147 </varlistentry>
148
8b78c993 149 <varlistentry>
e939674d
MA
150 <term>-E <replaceable class="parameter">engine</replaceable></term>
151 <listitem>
152 <para>
153 Specifies the cryptographic hardware to use.
154 </para>
155 <para>
156 When BIND is built with OpenSSL PKCS#11 support, this defaults
157 to the string "pkcs11", which identifies an OpenSSL engine
158 that can drive a cryptographic accelerator or hardware service
159 module. When BIND is built with native PKCS#11 cryptography
160 (--enable-native-pkcs11), it defaults to the path of the PKCS#11
161 provider library specified via "--with-pkcs11".
162 </para>
163 </listitem>
8b78c993
FD
164 </varlistentry>
165
2a31bd53 166 <varlistentry>
e939674d
MA
167 <term>-l <replaceable class="parameter">label</replaceable></term>
168 <listitem>
169 <para>
170 Specifies the label for a key pair in the crypto hardware.
171 </para>
172 <para>
173 When <acronym>BIND</acronym> 9 is built with OpenSSL-based
174 PKCS#11 support, the label is an arbitrary string that
175 identifies a particular key. It may be preceded by an
176 optional OpenSSL engine name, followed by a colon, as in
177 "pkcs11:<replaceable>keylabel</replaceable>".
178 </para>
179 <para>
180 When <acronym>BIND</acronym> 9 is built with native PKCS#11
181 support, the label is a PKCS#11 URI string in the format
182 "pkcs11:<option>keyword</option>=<replaceable>value</replaceable><optional>;<option>keyword</option>=<replaceable>value</replaceable>;...</optional>"
183 Keywords include "token", which identifies the HSM; "object", which
184 identifies the key; and "pin-source", which identifies a file from
185 which the HSM's PIN code can be obtained. The label will be
186 stored in the on-disk "private" file.
187 </para>
188 <para>
189 If the label contains a
190 <option>pin-source</option> field, tools using the generated
191 key files will be able to use the HSM for signing and other
192 operations without any need for an operator to manually enter
193 a PIN. Note: Making the HSM's PIN accessible in this manner
194 may reduce the security advantage of using an HSM; be sure
195 this is what you want to do before making use of this feature.
196 </para>
197 </listitem>
2a31bd53
FD
198 </varlistentry>
199
200 <varlistentry>
e939674d
MA
201 <term>-n <replaceable class="parameter">nametype</replaceable></term>
202 <listitem>
203 <para>
204 Specifies the owner type of the key. The value of
205 <option>nametype</option> must either be ZONE (for a DNSSEC
206 zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
207 a host (KEY)),
208 USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
209 These values are case insensitive.
210 </para>
211 </listitem>
1f821c10
FD
212 </varlistentry>
213
214 <varlistentry>
e939674d
MA
215 <term>-C</term>
216 <listitem>
217 <para>
1f821c10
FD
218 Compatibility mode: generates an old-style key, without
219 any metadata. By default, <command>dnssec-keyfromlabel</command>
220 will include the key's creation date in the metadata stored
221 with the private key, and other dates may be set there as well
222 (publication date, activation date, etc). Keys that include
223 this data may be incompatible with older versions of BIND; the
224 <option>-C</option> option suppresses them.
e939674d
MA
225 </para>
226 </listitem>
2a31bd53
FD
227 </varlistentry>
228
229 <varlistentry>
e939674d
MA
230 <term>-c <replaceable class="parameter">class</replaceable></term>
231 <listitem>
232 <para>
233 Indicates that the DNS record containing the key should have
234 the specified class. If not specified, class IN is used.
235 </para>
236 </listitem>
2a31bd53
FD
237 </varlistentry>
238
239 <varlistentry>
e939674d
MA
240 <term>-f <replaceable class="parameter">flag</replaceable></term>
241 <listitem>
242 <para>
243 Set the specified flag in the flag field of the KEY/DNSKEY record.
244 The only recognized flags are KSK (Key Signing Key) and REVOKE.
245 </para>
246 </listitem>
2a31bd53
FD
247 </varlistentry>
248
b843f577 249 <varlistentry>
e939674d
MA
250 <term>-G</term>
251 <listitem>
252 <para>
253 Generate a key, but do not publish it or sign with it. This
254 option is incompatible with -P and -A.
255 </para>
256 </listitem>
b843f577
EH
257 </varlistentry>
258
2a31bd53 259 <varlistentry>
e939674d
MA
260 <term>-h</term>
261 <listitem>
262 <para>
263 Prints a short summary of the options and arguments to
264 <command>dnssec-keyfromlabel</command>.
265 </para>
266 </listitem>
2a31bd53
FD
267 </varlistentry>
268
553ead32 269 <varlistentry>
e939674d
MA
270 <term>-K <replaceable class="parameter">directory</replaceable></term>
271 <listitem>
272 <para>
273 Sets the directory in which the key files are to be written.
274 </para>
275 </listitem>
553ead32
EH
276 </varlistentry>
277
2a31bd53 278 <varlistentry>
e939674d
MA
279 <term>-k</term>
280 <listitem>
281 <para>
282 Generate KEY records rather than DNSKEY records.
283 </para>
284 </listitem>
2a31bd53
FD
285 </varlistentry>
286
61bcc232 287 <varlistentry>
e939674d
MA
288 <term>-L <replaceable class="parameter">ttl</replaceable></term>
289 <listitem>
290 <para>
291 Sets the default TTL to use for this key when it is converted
292 into a DNSKEY RR. If the key is imported into a zone,
293 this is the TTL that will be used for it, unless there was
294 already a DNSKEY RRset in place, in which case the existing TTL
295 would take precedence. Setting the default TTL to
296 <literal>0</literal> or <literal>none</literal> removes it.
297 </para>
298 </listitem>
61bcc232
EH
299 </varlistentry>
300
2a31bd53 301 <varlistentry>
e939674d
MA
302 <term>-p <replaceable class="parameter">protocol</replaceable></term>
303 <listitem>
304 <para>
305 Sets the protocol value for the key. The protocol
306 is a number between 0 and 255. The default is 3 (DNSSEC).
307 Other possible values for this argument are listed in
308 RFC 2535 and its successors.
309 </para>
310 </listitem>
2a31bd53
FD
311 </varlistentry>
312
a60bf97f 313 <varlistentry>
e939674d
MA
314 <term>-S <replaceable class="parameter">key</replaceable></term>
315 <listitem>
316 <para>
317 Generate a key as an explicit successor to an existing key.
a60bf97f
EH
318 The name, algorithm, size, and type of the key will be set
319 to match the predecessor. The activation date of the new
320 key will be set to the inactivation date of the existing
321 one. The publication date will be set to the activation
322 date minus the prepublication interval, which defaults to
323 30 days.
e939674d
MA
324 </para>
325 </listitem>
a60bf97f
EH
326 </varlistentry>
327
2a31bd53 328 <varlistentry>
e939674d
MA
329 <term>-t <replaceable class="parameter">type</replaceable></term>
330 <listitem>
331 <para>
332 Indicates the use of the key. <option>type</option> must be
333 one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
334 is AUTHCONF. AUTH refers to the ability to authenticate
335 data, and CONF the ability to encrypt data.
336 </para>
337 </listitem>
2a31bd53
FD
338 </varlistentry>
339
340 <varlistentry>
e939674d
MA
341 <term>-v <replaceable class="parameter">level</replaceable></term>
342 <listitem>
343 <para>
344 Sets the debugging level.
345 </para>
346 </listitem>
2a31bd53
FD
347 </varlistentry>
348
42782931
MS
349 <varlistentry>
350 <term>-V</term>
e939674d 351 <listitem>
42782931
MS
352 <para>
353 Prints version information.
354 </para>
e939674d 355 </listitem>
42782931
MS
356 </varlistentry>
357
8a198fa7 358 <varlistentry>
e939674d
MA
359 <term>-y</term>
360 <listitem>
361 <para>
362 Allows DNSSEC key files to be generated even if the key ID
8a198fa7
EH
363 would collide with that of an existing key, in the event of
364 either key being revoked. (This is only safe to use if you
e939674d
MA
365 are sure you won't be using RFC 5011 trust anchor maintenance
366 with either of the keys involved.)
367 </para>
368 </listitem>
8a198fa7
EH
369 </varlistentry>
370
2a31bd53 371 </variablelist>
14a656f9 372 </refsection>
2a31bd53 373
14a656f9 374 <refsection><info><title>TIMING OPTIONS</title></info>
30eec077 375
1f821c10
FD
376
377 <para>
378 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
379 If the argument begins with a '+' or '-', it is interpreted as
380 an offset from the present time. For convenience, if such an offset
381 is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
382 then the offset is computed in years (defined as 365 24-hour days,
383 ignoring leap years), months (defined as 30 24-hour days), weeks,
384 days, hours, or minutes, respectively. Without a suffix, the offset
a165a17a
EH
385 is computed in seconds. To explicitly prevent a date from being
386 set, use 'none' or 'never'.
1f821c10
FD
387 </para>
388
389 <variablelist>
390 <varlistentry>
e939674d
MA
391 <term>-P <replaceable class="parameter">date/offset</replaceable></term>
392 <listitem>
393 <para>
394 Sets the date on which a key is to be published to the zone.
395 After that date, the key will be included in the zone but will
396 not be used to sign it. If not set, and if the -G option has
397 not been used, the default is "now".
398 </para>
399 </listitem>
1f821c10
FD
400 </varlistentry>
401
402 <varlistentry>
e939674d
MA
403 <term>-P sync <replaceable class="parameter">date/offset</replaceable></term>
404 <listitem>
405 <para>
406 Sets the date on which the CDS and CDNSKEY records which match
407 this key are to be published to the zone.
408 </para>
409 </listitem>
1f821c10
FD
410 </varlistentry>
411
412 <varlistentry>
e939674d
MA
413 <term>-A <replaceable class="parameter">date/offset</replaceable></term>
414 <listitem>
415 <para>
416 Sets the date on which the key is to be activated. After that
417 date, the key will be included in the zone and used to sign
418 it. If not set, and if the -G option has not been used, the
419 default is "now".
420 </para>
421 </listitem>
1f821c10
FD
422 </varlistentry>
423
424 <varlistentry>
e939674d
MA
425 <term>-R <replaceable class="parameter">date/offset</replaceable></term>
426 <listitem>
427 <para>
428 Sets the date on which the key is to be revoked. After that
429 date, the key will be flagged as revoked. It will be included
430 in the zone and will be used to sign it.
431 </para>
432 </listitem>
1f821c10
FD
433 </varlistentry>
434
435 <varlistentry>
e939674d
MA
436 <term>-I <replaceable class="parameter">date/offset</replaceable></term>
437 <listitem>
438 <para>
439 Sets the date on which the key is to be retired. After that
440 date, the key will still be included in the zone, but it
441 will not be used to sign it.
442 </para>
443 </listitem>
444 </varlistentry>
445
446 <varlistentry>
447 <term>-D <replaceable class="parameter">date/offset</replaceable></term>
448 <listitem>
449 <para>
450 Sets the date on which the key is to be deleted. After that
451 date, the key will no longer be included in the zone. (It
452 may remain in the key repository, however.)
453 </para>
454 </listitem>
455 </varlistentry>
456
457 <varlistentry>
458 <term>-D sync <replaceable class="parameter">date/offset</replaceable></term>
459 <listitem>
460 <para>
461 Sets the date on which the CDS and CDNSKEY records which match
462 this key are to be deleted.
463 </para>
464 </listitem>
1f821c10 465 </varlistentry>
a60bf97f
EH
466
467 <varlistentry>
45afdb26
EH
468 <term>-i <replaceable class="parameter">interval</replaceable></term>
469 <listitem>
470 <para>
471 Sets the prepublication interval for a key. If set, then
472 the publication and activation dates must be separated by at least
473 this much time. If the activation date is specified but the
474 publication date isn't, then the publication date will default
475 to this much time before the activation date; conversely, if
476 the publication date is specified but activation date isn't,
477 then activation will be set to this much time after publication.
478 </para>
479 <para>
480 If the key is being created as an explicit successor to another
481 key, then the default prepublication interval is 30 days;
482 otherwise it is zero.
483 </para>
484 <para>
485 As with date offsets, if the argument is followed by one of
486 the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
487 interval is measured in years, months, weeks, days, hours,
488 or minutes, respectively. Without a suffix, the interval is
489 measured in seconds.
490 </para>
491 </listitem>
a60bf97f
EH
492 </varlistentry>
493
1f821c10 494 </variablelist>
14a656f9 495 </refsection>
1f821c10 496
14a656f9 497 <refsection><info><title>GENERATED KEY FILES</title></info>
30eec077 498
2a31bd53
FD
499 <para>
500 When <command>dnssec-keyfromlabel</command> completes
501 successfully,
502 it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
503 to the standard output. This is an identification string for
504 the key files it has generated.
505 </para>
506 <itemizedlist>
507 <listitem>
e939674d
MA
508 <para><filename>nnnn</filename> is the key name.
509 </para>
2a31bd53
FD
510 </listitem>
511 <listitem>
e939674d
MA
512 <para><filename>aaa</filename> is the numeric representation
513 of the algorithm.
514 </para>
2a31bd53
FD
515 </listitem>
516 <listitem>
e939674d
MA
517 <para><filename>iiiii</filename> is the key identifier (or
518 footprint).
519 </para>
2a31bd53
FD
520 </listitem>
521 </itemizedlist>
30eec077 522 <para><command>dnssec-keyfromlabel</command>
2a31bd53
FD
523 creates two files, with names based
524 on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
525 contains the public key, and
526 <filename>Knnnn.+aaa+iiiii.private</filename> contains the
1f821c10 527 private key.
2a31bd53
FD
528 </para>
529 <para>
530 The <filename>.key</filename> file contains a DNS KEY record
531 that
532 can be inserted into a zone file (directly or with a $INCLUDE
533 statement).
534 </para>
535 <para>
1f821c10
FD
536 The <filename>.private</filename> file contains
537 algorithm-specific
2a31bd53
FD
538 fields. For obvious security reasons, this file does not have
539 general read permission.
540 </para>
14a656f9 541 </refsection>
2a31bd53 542
14a656f9 543 <refsection><info><title>SEE ALSO</title></info>
30eec077 544
2a31bd53 545 <para><citerefentry>
e939674d 546 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
2a31bd53
FD
547 </citerefentry>,
548 <citerefentry>
e939674d 549 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
2a31bd53
FD
550 </citerefentry>,
551 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
08c67b5b
EH
552 <citetitle>RFC 4034</citetitle>,
553 <citetitle>The PKCS#11 URI Scheme (draft-pechanec-pkcs11uri-13)</citetitle>.
2a31bd53 554 </para>
14a656f9 555 </refsection>
2a31bd53 556
14a656f9 557</refentry>