Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_13_...
[ipreg/bind9.git] / bin / dnssec / dnssec-keyfromlabel.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <!--
3 - Copyright (C) 2008-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
4 -
5 - This Source Code Form is subject to the terms of the Mozilla Public
6 - License, v. 2.0. If a copy of the MPL was not distributed with this
7 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 -->
9 <html lang="en">
10 <head>
11 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
12 <title>dnssec-keyfromlabel</title>
13 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
14 </head>
15 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
16 <a name="man.dnssec-keyfromlabel"></a><div class="titlepage"></div>
22 <div class="refnamediv">
23 <h2>Name</h2>
24 <p>
25 <span class="application">dnssec-keyfromlabel</span>
26 &#8212; DNSSEC key generation tool
27 </p>
28 </div>
32 <div class="refsynopsisdiv">
33 <h2>Synopsis</h2>
34 <div class="cmdsynopsis"><p>
35 <code class="command">dnssec-keyfromlabel</code>
36 {-l <em class="replaceable"><code>label</code></em>}
37 [<code class="option">-3</code>]
38 [<code class="option">-a <em class="replaceable"><code>algorithm</code></em></code>]
39 [<code class="option">-A <em class="replaceable"><code>date/offset</code></em></code>]
40 [<code class="option">-c <em class="replaceable"><code>class</code></em></code>]
41 [<code class="option">-D <em class="replaceable"><code>date/offset</code></em></code>]
42 [<code class="option">-D sync <em class="replaceable"><code>date/offset</code></em></code>]
43 [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>]
44 [<code class="option">-f <em class="replaceable"><code>flag</code></em></code>]
45 [<code class="option">-G</code>]
46 [<code class="option">-I <em class="replaceable"><code>date/offset</code></em></code>]
47 [<code class="option">-i <em class="replaceable"><code>interval</code></em></code>]
48 [<code class="option">-k</code>]
49 [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>]
50 [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>]
51 [<code class="option">-n <em class="replaceable"><code>nametype</code></em></code>]
52 [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>]
53 [<code class="option">-P sync <em class="replaceable"><code>date/offset</code></em></code>]
54 [<code class="option">-p <em class="replaceable"><code>protocol</code></em></code>]
55 [<code class="option">-R <em class="replaceable"><code>date/offset</code></em></code>]
56 [<code class="option">-S <em class="replaceable"><code>key</code></em></code>]
57 [<code class="option">-t <em class="replaceable"><code>type</code></em></code>]
58 [<code class="option">-v <em class="replaceable"><code>level</code></em></code>]
59 [<code class="option">-V</code>]
60 [<code class="option">-y</code>]
61 {name}
62 </p></div>
63 </div>
65 <div class="refsection">
66 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
68 <p><span class="command"><strong>dnssec-keyfromlabel</strong></span>
69 generates a key pair of files that referencing a key object stored
70 in a cryptographic hardware service module (HSM). The private key
71 file can be used for DNSSEC signing of zone data as if it were a
72 conventional signing key created by <span class="command"><strong>dnssec-keygen</strong></span>,
73 but the key material is stored within the HSM, and the actual signing
74 takes place there.
75 </p>
76 <p>
77 The <code class="option">name</code> of the key is specified on the command
78 line. This must match the name of the zone for which the key is
79 being generated.
80 </p>
81 </div>
83 <div class="refsection">
84 <a name="id-1.8"></a><h2>OPTIONS</h2>
87 <div class="variablelist"><dl class="variablelist">
88 <dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
89 <dd>
90 <p>
91 Selects the cryptographic algorithm. The value of
92 <code class="option">algorithm</code> must be one of RSASHA1,
94 ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448.
95 </p>
96 <p>
97 If no algorithm is specified, then RSASHA1 will be used by
98 default, unless the <code class="option">-3</code> option is specified,
99 in which case NSEC3RSASHA1 will be used instead. (If
100 <code class="option">-3</code> is used and an algorithm is specified,
101 that algorithm will be checked for compatibility with NSEC3.)
102 </p>
103 <p>
104 These values are case insensitive. In some cases, abbreviations
105 are supported, such as ECDSA256 for ECDSAP256SHA256 and
106 ECDSA384 for ECDSAP384SHA384. If RSASHA1 is specified
107 along with the <code class="option">-3</code> option, then NSEC3RSASHA1
108 will be used instead.
109 </p>
110 <p>
111 As of BIND 9.12.0, this option is mandatory except when using
112 the <code class="option">-S</code> option (which copies the algorithm from
113 the predecessory key). Previously, the default for newly
114 generated keys was RSASHA1.
115 </p>
116 </dd>
117 <dt><span class="term">-3</span></dt>
118 <dd>
119 <p>
120 Use an NSEC3-capable algorithm to generate a DNSSEC key.
121 If this option is used with an algorithm that has both
122 NSEC and NSEC3 versions, then the NSEC3 version will be
123 used; for example, <span class="command"><strong>dnssec-keygen -3a RSASHA1</strong></span>
124 specifies the NSEC3RSASHA1 algorithm.
125 </p>
126 </dd>
127 <dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt>
128 <dd>
129 <p>
130 Specifies the cryptographic hardware to use.
131 </p>
132 <p>
133 When BIND is built with OpenSSL PKCS#11 support, this defaults
134 to the string "pkcs11", which identifies an OpenSSL engine
135 that can drive a cryptographic accelerator or hardware service
136 module. When BIND is built with native PKCS#11 cryptography
137 (--enable-native-pkcs11), it defaults to the path of the PKCS#11
138 provider library specified via "--with-pkcs11".
139 </p>
140 </dd>
141 <dt><span class="term">-l <em class="replaceable"><code>label</code></em></span></dt>
142 <dd>
143 <p>
144 Specifies the label for a key pair in the crypto hardware.
145 </p>
146 <p>
147 When <acronym class="acronym">BIND</acronym> 9 is built with OpenSSL-based
148 PKCS#11 support, the label is an arbitrary string that
149 identifies a particular key. It may be preceded by an
150 optional OpenSSL engine name, followed by a colon, as in
151 "pkcs11:<em class="replaceable"><code>keylabel</code></em>".
152 </p>
153 <p>
154 When <acronym class="acronym">BIND</acronym> 9 is built with native PKCS#11
155 support, the label is a PKCS#11 URI string in the format
156 "pkcs11:<code class="option">keyword</code>=<em class="replaceable"><code>value</code></em>[<span class="optional">;<code class="option">keyword</code>=<em class="replaceable"><code>value</code></em>;...</span>]"
157 Keywords include "token", which identifies the HSM; "object", which
158 identifies the key; and "pin-source", which identifies a file from
159 which the HSM's PIN code can be obtained. The label will be
160 stored in the on-disk "private" file.
161 </p>
162 <p>
163 If the label contains a
164 <code class="option">pin-source</code> field, tools using the generated
165 key files will be able to use the HSM for signing and other
166 operations without any need for an operator to manually enter
167 a PIN. Note: Making the HSM's PIN accessible in this manner
168 may reduce the security advantage of using an HSM; be sure
169 this is what you want to do before making use of this feature.
170 </p>
171 </dd>
172 <dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt>
173 <dd>
174 <p>
175 Specifies the owner type of the key. The value of
176 <code class="option">nametype</code> must either be ZONE (for a DNSSEC
177 zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
178 a host (KEY)),
179 USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
180 These values are case insensitive.
181 </p>
182 </dd>
183 <dt><span class="term">-C</span></dt>
184 <dd>
185 <p>
186 Compatibility mode: generates an old-style key, without
187 any metadata. By default, <span class="command"><strong>dnssec-keyfromlabel</strong></span>
188 will include the key's creation date in the metadata stored
189 with the private key, and other dates may be set there as well
190 (publication date, activation date, etc). Keys that include
191 this data may be incompatible with older versions of BIND; the
192 <code class="option">-C</code> option suppresses them.
193 </p>
194 </dd>
195 <dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
196 <dd>
197 <p>
198 Indicates that the DNS record containing the key should have
199 the specified class. If not specified, class IN is used.
200 </p>
201 </dd>
202 <dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt>
203 <dd>
204 <p>
205 Set the specified flag in the flag field of the KEY/DNSKEY record.
206 The only recognized flags are KSK (Key Signing Key) and REVOKE.
207 </p>
208 </dd>
209 <dt><span class="term">-G</span></dt>
210 <dd>
211 <p>
212 Generate a key, but do not publish it or sign with it. This
213 option is incompatible with -P and -A.
214 </p>
215 </dd>
216 <dt><span class="term">-h</span></dt>
217 <dd>
218 <p>
219 Prints a short summary of the options and arguments to
220 <span class="command"><strong>dnssec-keyfromlabel</strong></span>.
221 </p>
222 </dd>
223 <dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
224 <dd>
225 <p>
226 Sets the directory in which the key files are to be written.
227 </p>
228 </dd>
229 <dt><span class="term">-k</span></dt>
230 <dd>
231 <p>
232 Generate KEY records rather than DNSKEY records.
233 </p>
234 </dd>
235 <dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt>
236 <dd>
237 <p>
238 Sets the default TTL to use for this key when it is converted
239 into a DNSKEY RR. If the key is imported into a zone,
240 this is the TTL that will be used for it, unless there was
241 already a DNSKEY RRset in place, in which case the existing TTL
242 would take precedence. Setting the default TTL to
243 <code class="literal">0</code> or <code class="literal">none</code> removes it.
244 </p>
245 </dd>
246 <dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt>
247 <dd>
248 <p>
249 Sets the protocol value for the key. The protocol
250 is a number between 0 and 255. The default is 3 (DNSSEC).
251 Other possible values for this argument are listed in
252 RFC 2535 and its successors.
253 </p>
254 </dd>
255 <dt><span class="term">-S <em class="replaceable"><code>key</code></em></span></dt>
256 <dd>
257 <p>
258 Generate a key as an explicit successor to an existing key.
259 The name, algorithm, size, and type of the key will be set
260 to match the predecessor. The activation date of the new
261 key will be set to the inactivation date of the existing
262 one. The publication date will be set to the activation
263 date minus the prepublication interval, which defaults to
264 30 days.
265 </p>
266 </dd>
267 <dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt>
268 <dd>
269 <p>
270 Indicates the use of the key. <code class="option">type</code> must be
271 one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
272 is AUTHCONF. AUTH refers to the ability to authenticate
273 data, and CONF the ability to encrypt data.
274 </p>
275 </dd>
276 <dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
277 <dd>
278 <p>
279 Sets the debugging level.
280 </p>
281 </dd>
282 <dt><span class="term">-V</span></dt>
283 <dd>
284 <p>
285 Prints version information.
286 </p>
287 </dd>
288 <dt><span class="term">-y</span></dt>
289 <dd>
290 <p>
291 Allows DNSSEC key files to be generated even if the key ID
292 would collide with that of an existing key, in the event of
293 either key being revoked. (This is only safe to use if you
294 are sure you won't be using RFC 5011 trust anchor maintenance
295 with either of the keys involved.)
296 </p>
297 </dd>
298 </dl></div>
299 </div>
301 <div class="refsection">
302 <a name="id-1.9"></a><h2>TIMING OPTIONS</h2>
305 <p>
306 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
307 If the argument begins with a '+' or '-', it is interpreted as
308 an offset from the present time. For convenience, if such an offset
309 is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
310 then the offset is computed in years (defined as 365 24-hour days,
311 ignoring leap years), months (defined as 30 24-hour days), weeks,
312 days, hours, or minutes, respectively. Without a suffix, the offset
313 is computed in seconds. To explicitly prevent a date from being
314 set, use 'none' or 'never'.
315 </p>
317 <div class="variablelist"><dl class="variablelist">
318 <dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt>
319 <dd>
320 <p>
321 Sets the date on which a key is to be published to the zone.
322 After that date, the key will be included in the zone but will
323 not be used to sign it. If not set, and if the -G option has
324 not been used, the default is "now".
325 </p>
326 </dd>
327 <dt><span class="term">-P sync <em class="replaceable"><code>date/offset</code></em></span></dt>
328 <dd>
329 <p>
330 Sets the date on which the CDS and CDNSKEY records which match
331 this key are to be published to the zone.
332 </p>
333 </dd>
334 <dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt>
335 <dd>
336 <p>
337 Sets the date on which the key is to be activated. After that
338 date, the key will be included in the zone and used to sign
339 it. If not set, and if the -G option has not been used, the
340 default is "now".
341 </p>
342 </dd>
343 <dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt>
344 <dd>
345 <p>
346 Sets the date on which the key is to be revoked. After that
347 date, the key will be flagged as revoked. It will be included
348 in the zone and will be used to sign it.
349 </p>
350 </dd>
351 <dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt>
352 <dd>
353 <p>
354 Sets the date on which the key is to be retired. After that
355 date, the key will still be included in the zone, but it
356 will not be used to sign it.
357 </p>
358 </dd>
359 <dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt>
360 <dd>
361 <p>
362 Sets the date on which the key is to be deleted. After that
363 date, the key will no longer be included in the zone. (It
364 may remain in the key repository, however.)
365 </p>
366 </dd>
367 <dt><span class="term">-D sync <em class="replaceable"><code>date/offset</code></em></span></dt>
368 <dd>
369 <p>
370 Sets the date on which the CDS and CDNSKEY records which match
371 this key are to be deleted.
372 </p>
373 </dd>
374 <dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt>
375 <dd>
376 <p>
377 Sets the prepublication interval for a key. If set, then
378 the publication and activation dates must be separated by at least
379 this much time. If the activation date is specified but the
380 publication date isn't, then the publication date will default
381 to this much time before the activation date; conversely, if
382 the publication date is specified but activation date isn't,
383 then activation will be set to this much time after publication.
384 </p>
385 <p>
386 If the key is being created as an explicit successor to another
387 key, then the default prepublication interval is 30 days;
388 otherwise it is zero.
389 </p>
390 <p>
391 As with date offsets, if the argument is followed by one of
392 the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
393 interval is measured in years, months, weeks, days, hours,
394 or minutes, respectively. Without a suffix, the interval is
395 measured in seconds.
396 </p>
397 </dd>
398 </dl></div>
399 </div>
401 <div class="refsection">
402 <a name="id-1.10"></a><h2>GENERATED KEY FILES</h2>
404 <p>
405 When <span class="command"><strong>dnssec-keyfromlabel</strong></span> completes
406 successfully,
407 it prints a string of the form <code class="filename">Knnnn.+aaa+iiiii</code>
408 to the standard output. This is an identification string for
409 the key files it has generated.
410 </p>
411 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
412 <li class="listitem">
413 <p><code class="filename">nnnn</code> is the key name.
414 </p>
415 </li>
416 <li class="listitem">
417 <p><code class="filename">aaa</code> is the numeric representation
418 of the algorithm.
419 </p>
420 </li>
421 <li class="listitem">
422 <p><code class="filename">iiiii</code> is the key identifier (or
423 footprint).
424 </p>
425 </li>
426 </ul></div>
427 <p><span class="command"><strong>dnssec-keyfromlabel</strong></span>
428 creates two files, with names based
429 on the printed string. <code class="filename">Knnnn.+aaa+iiiii.key</code>
430 contains the public key, and
431 <code class="filename">Knnnn.+aaa+iiiii.private</code> contains the
432 private key.
433 </p>
434 <p>
435 The <code class="filename">.key</code> file contains a DNS KEY record
436 that
437 can be inserted into a zone file (directly or with a $INCLUDE
438 statement).
439 </p>
440 <p>
441 The <code class="filename">.private</code> file contains
442 algorithm-specific
443 fields. For obvious security reasons, this file does not have
444 general read permission.
445 </p>
446 </div>
448 <div class="refsection">
449 <a name="id-1.11"></a><h2>SEE ALSO</h2>
451 <p><span class="citerefentry">
452 <span class="refentrytitle">dnssec-keygen</span>(8)
453 </span>,
454 <span class="citerefentry">
455 <span class="refentrytitle">dnssec-signzone</span>(8)
456 </span>,
457 <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
458 <em class="citetitle">RFC 4034</em>,
459 <em class="citetitle">The PKCS#11 URI Scheme (draft-pechanec-pkcs11uri-13)</em>.
460 </p>
461 </div>
463 </div></body>
464 </html>