Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_13_...
[ipreg/bind9.git] / bin / dnssec / dnssec-keyfromlabel.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-keyfromlabel">
14 <info>
15 <date>2014-02-27</date>
16 </info>
17 <refentryinfo>
18 <date>August 27, 2015</date>
19 <corpname>ISC</corpname>
20 <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
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>
36 <year>2008</year>
37 <year>2009</year>
38 <year>2010</year>
39 <year>2011</year>
40 <year>2012</year>
41 <year>2014</year>
42 <year>2015</year>
43 <year>2016</year>
44 <year>2017</year>
45 <year>2018</year>
46 <year>2019</year>
47 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
48 </copyright>
49 </docinfo>
50
51 <refsynopsisdiv>
52 <cmdsynopsis sepchar=" ">
53 <command>dnssec-keyfromlabel</command>
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>
60 <arg choice="opt" rep="norepeat"><option>-D sync <replaceable class="parameter">date/offset</replaceable></option></arg>
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>
71 <arg choice="opt" rep="norepeat"><option>-P sync <replaceable class="parameter">date/offset</replaceable></option></arg>
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>
80 </cmdsynopsis>
81 </refsynopsisdiv>
82
83 <refsection><info><title>DESCRIPTION</title></info>
84
85 <para><command>dnssec-keyfromlabel</command>
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.
92 </para>
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>
98 </refsection>
99
100 <refsection><info><title>OPTIONS</title></info>
101
102
103 <variablelist>
104 <varlistentry>
105 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
106 <listitem>
107 <para>
108 Selects the cryptographic algorithm. The value of
109 <option>algorithm</option> must be one of RSASHA1,
110 NSEC3RSASHA1, RSASHA256, RSASHA512,
111 ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448.
112 </para>
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>
121 These values are case insensitive. In some cases, abbreviations
122 are supported, such as ECDSA256 for ECDSAP256SHA256 and
123 ECDSA384 for ECDSAP384SHA384. If RSASHA1 is specified
124 along with the <option>-3</option> option, then NSEC3RSASHA1
125 will be used instead.
126 </para>
127 <para>
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.
132 </para>
133 </listitem>
134 </varlistentry>
135
136 <varlistentry>
137 <term>-3</term>
138 <listitem>
139 <para>
140 Use an NSEC3-capable algorithm to generate a DNSSEC key.
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.
145 </para>
146 </listitem>
147 </varlistentry>
148
149 <varlistentry>
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>
164 </varlistentry>
165
166 <varlistentry>
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>
198 </varlistentry>
199
200 <varlistentry>
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>
212 </varlistentry>
213
214 <varlistentry>
215 <term>-C</term>
216 <listitem>
217 <para>
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.
225 </para>
226 </listitem>
227 </varlistentry>
228
229 <varlistentry>
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>
237 </varlistentry>
238
239 <varlistentry>
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>
247 </varlistentry>
248
249 <varlistentry>
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>
257 </varlistentry>
258
259 <varlistentry>
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>
267 </varlistentry>
268
269 <varlistentry>
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>
276 </varlistentry>
277
278 <varlistentry>
279 <term>-k</term>
280 <listitem>
281 <para>
282 Generate KEY records rather than DNSKEY records.
283 </para>
284 </listitem>
285 </varlistentry>
286
287 <varlistentry>
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>
299 </varlistentry>
300
301 <varlistentry>
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>
311 </varlistentry>
312
313 <varlistentry>
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.
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.
324 </para>
325 </listitem>
326 </varlistentry>
327
328 <varlistentry>
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>
338 </varlistentry>
339
340 <varlistentry>
341 <term>-v <replaceable class="parameter">level</replaceable></term>
342 <listitem>
343 <para>
344 Sets the debugging level.
345 </para>
346 </listitem>
347 </varlistentry>
348
349 <varlistentry>
350 <term>-V</term>
351 <listitem>
352 <para>
353 Prints version information.
354 </para>
355 </listitem>
356 </varlistentry>
357
358 <varlistentry>
359 <term>-y</term>
360 <listitem>
361 <para>
362 Allows DNSSEC key files to be generated even if the key ID
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
365 are sure you won't be using RFC 5011 trust anchor maintenance
366 with either of the keys involved.)
367 </para>
368 </listitem>
369 </varlistentry>
370
371 </variablelist>
372 </refsection>
373
374 <refsection><info><title>TIMING OPTIONS</title></info>
375
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
385 is computed in seconds. To explicitly prevent a date from being
386 set, use 'none' or 'never'.
387 </para>
388
389 <variablelist>
390 <varlistentry>
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>
400 </varlistentry>
401
402 <varlistentry>
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>
410 </varlistentry>
411
412 <varlistentry>
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>
422 </varlistentry>
423
424 <varlistentry>
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>
433 </varlistentry>
434
435 <varlistentry>
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>
465 </varlistentry>
466
467 <varlistentry>
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>
492 </varlistentry>
493
494 </variablelist>
495 </refsection>
496
497 <refsection><info><title>GENERATED KEY FILES</title></info>
498
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>
508 <para><filename>nnnn</filename> is the key name.
509 </para>
510 </listitem>
511 <listitem>
512 <para><filename>aaa</filename> is the numeric representation
513 of the algorithm.
514 </para>
515 </listitem>
516 <listitem>
517 <para><filename>iiiii</filename> is the key identifier (or
518 footprint).
519 </para>
520 </listitem>
521 </itemizedlist>
522 <para><command>dnssec-keyfromlabel</command>
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
527 private key.
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>
536 The <filename>.private</filename> file contains
537 algorithm-specific
538 fields. For obvious security reasons, this file does not have
539 general read permission.
540 </para>
541 </refsection>
542
543 <refsection><info><title>SEE ALSO</title></info>
544
545 <para><citerefentry>
546 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
547 </citerefentry>,
548 <citerefentry>
549 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
550 </citerefentry>,
551 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
552 <citetitle>RFC 4034</citetitle>,
553 <citetitle>The PKCS#11 URI Scheme (draft-pechanec-pkcs11uri-13)</citetitle>.
554 </para>
555 </refsection>
556
557 </refentry>