Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-keyfromlabel.html
CommitLineData
63fe88e8 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
90f35c2f 2<!--
b4d3f782 3 - Copyright (C) 2008-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
90f35c2f 4 -
6807a2dc
TU
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/.
90f35c2f 8-->
63fe88e8 9<html lang="en">
90f35c2f
FD
10<head>
11<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
12<title>dnssec-keyfromlabel</title>
fd2597f7 13<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
90f35c2f 14</head>
fd2597f7 15<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
90f35c2f 16<a name="man.dnssec-keyfromlabel"></a><div class="titlepage"></div>
16fde7f0
TU
17
18
19
20
21
22 <div class="refnamediv">
90f35c2f 23<h2>Name</h2>
16fde7f0
TU
24<p>
25 <span class="application">dnssec-keyfromlabel</span>
26 &#8212; DNSSEC key generation tool
27 </p>
90f35c2f 28</div>
16fde7f0
TU
29
30
31
32 <div class="refsynopsisdiv">
90f35c2f 33<h2>Synopsis</h2>
16fde7f0
TU
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>
64
65 <div class="refsection">
fd2597f7 66<a name="id-1.7"></a><h2>DESCRIPTION</h2>
16fde7f0
TU
67
68 <p><span class="command"><strong>dnssec-keyfromlabel</strong></span>
794b79e6
TU
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
2eeb74d1 72 conventional signing key created by <span class="command"><strong>dnssec-keygen</strong></span>,
794b79e6
TU
73 but the key material is stored within the HSM, and the actual signing
74 takes place there.
90f35c2f 75 </p>
16fde7f0 76 <p>
c7d32c0b
AU
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>
16fde7f0
TU
81 </div>
82
83 <div class="refsection">
fd2597f7 84<a name="id-1.8"></a><h2>OPTIONS</h2>
16fde7f0
TU
85
86
87 <div class="variablelist"><dl class="variablelist">
90f35c2f
FD
88<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
89<dd>
16fde7f0 90 <p>
90f35c2f 91 Selects the cryptographic algorithm. The value of
b4d3f782 92 <code class="option">algorithm</code> must be one of RSASHA1,
db1cd0d9 93 NSEC3RSASHA1, RSASHA256, RSASHA512,
8cc38b58 94 ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448.
90f35c2f 95 </p>
16fde7f0 96 <p>
e62b9c9c
TU
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>
16fde7f0 103 <p>
e640ea93
TU
104 These values are case insensitive. In some cases, abbreviations
105 are supported, such as ECDSA256 for ECDSAP256SHA256 and
db1cd0d9 106 ECDSA384 for ECDSAP384SHA384. If RSASHA1 is specified
e640ea93 107 along with the <code class="option">-3</code> option, then NSEC3RSASHA1
db1cd0d9 108 will be used instead.
e62b9c9c 109 </p>
16fde7f0 110 <p>
e640ea93
TU
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.
e62b9c9c 115 </p>
16fde7f0 116 </dd>
2a6d4c99 117<dt><span class="term">-3</span></dt>
16fde7f0
TU
118<dd>
119 <p>
2a6d4c99 120 Use an NSEC3-capable algorithm to generate a DNSSEC key.
e640ea93
TU
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.
16fde7f0
TU
125 </p>
126 </dd>
8ec3c085 127<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt>
6ea23853 128<dd>
16fde7f0 129 <p>
e62b9c9c
TU
130 Specifies the cryptographic hardware to use.
131 </p>
16fde7f0 132 <p>
e62b9c9c
TU
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>
16fde7f0 140 </dd>
90f35c2f 141<dt><span class="term">-l <em class="replaceable"><code>label</code></em></span></dt>
bbbf2e27 142<dd>
16fde7f0 143 <p>
e62b9c9c
TU
144 Specifies the label for a key pair in the crypto hardware.
145 </p>
16fde7f0 146 <p>
e62b9c9c
TU
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>
16fde7f0 153 <p>
e62b9c9c
TU
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>
16fde7f0 162 <p>
e62b9c9c
TU
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>
16fde7f0 171 </dd>
90f35c2f 172<dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt>
16fde7f0
TU
173<dd>
174 <p>
e62b9c9c
TU
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.
16fde7f0
TU
181 </p>
182 </dd>
c7d32c0b 183<dt><span class="term">-C</span></dt>
16fde7f0
TU
184<dd>
185 <p>
c7d32c0b 186 Compatibility mode: generates an old-style key, without
2eeb74d1 187 any metadata. By default, <span class="command"><strong>dnssec-keyfromlabel</strong></span>
c7d32c0b
AU
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.
16fde7f0
TU
193 </p>
194 </dd>
90f35c2f 195<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
16fde7f0
TU
196<dd>
197 <p>
e62b9c9c
TU
198 Indicates that the DNS record containing the key should have
199 the specified class. If not specified, class IN is used.
16fde7f0
TU
200 </p>
201 </dd>
90f35c2f 202<dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt>
16fde7f0
TU
203<dd>
204 <p>
e62b9c9c
TU
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.
16fde7f0
TU
207 </p>
208 </dd>
f8e3e03c 209<dt><span class="term">-G</span></dt>
16fde7f0
TU
210<dd>
211 <p>
e62b9c9c
TU
212 Generate a key, but do not publish it or sign with it. This
213 option is incompatible with -P and -A.
16fde7f0
TU
214 </p>
215 </dd>
90f35c2f 216<dt><span class="term">-h</span></dt>
16fde7f0
TU
217<dd>
218 <p>
e62b9c9c
TU
219 Prints a short summary of the options and arguments to
220 <span class="command"><strong>dnssec-keyfromlabel</strong></span>.
16fde7f0
TU
221 </p>
222 </dd>
0a7ed886 223<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
16fde7f0
TU
224<dd>
225 <p>
e62b9c9c 226 Sets the directory in which the key files are to be written.
16fde7f0
TU
227 </p>
228 </dd>
90f35c2f 229<dt><span class="term">-k</span></dt>
16fde7f0
TU
230<dd>
231 <p>
e62b9c9c 232 Generate KEY records rather than DNSKEY records.
16fde7f0
TU
233 </p>
234 </dd>
a3f8c8e2 235<dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt>
16fde7f0
TU
236<dd>
237 <p>
e62b9c9c
TU
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.
16fde7f0
TU
244 </p>
245 </dd>
90f35c2f 246<dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt>
16fde7f0
TU
247<dd>
248 <p>
e62b9c9c
TU
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.
16fde7f0
TU
253 </p>
254 </dd>
794b79e6 255<dt><span class="term">-S <em class="replaceable"><code>key</code></em></span></dt>
16fde7f0
TU
256<dd>
257 <p>
e62b9c9c 258 Generate a key as an explicit successor to an existing key.
794b79e6
TU
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.
16fde7f0
TU
265 </p>
266 </dd>
90f35c2f 267<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt>
16fde7f0
TU
268<dd>
269 <p>
e62b9c9c
TU
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.
16fde7f0
TU
274 </p>
275 </dd>
90f35c2f 276<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
16fde7f0
TU
277<dd>
278 <p>
e62b9c9c 279 Sets the debugging level.
16fde7f0
TU
280 </p>
281 </dd>
6f120589 282<dt><span class="term">-V</span></dt>
16fde7f0
TU
283<dd>
284 <p>
6f120589 285 Prints version information.
16fde7f0
TU
286 </p>
287 </dd>
a3416b0a 288<dt><span class="term">-y</span></dt>
16fde7f0
TU
289<dd>
290 <p>
e62b9c9c 291 Allows DNSSEC key files to be generated even if the key ID
a3416b0a
AU
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
e62b9c9c
TU
294 are sure you won't be using RFC 5011 trust anchor maintenance
295 with either of the keys involved.)
16fde7f0
TU
296 </p>
297 </dd>
90f35c2f 298</dl></div>
16fde7f0
TU
299 </div>
300
301 <div class="refsection">
fd2597f7 302<a name="id-1.9"></a><h2>TIMING OPTIONS</h2>
16fde7f0
TU
303
304
305 <p>
c7d32c0b
AU
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
bbbf2e27
TU
313 is computed in seconds. To explicitly prevent a date from being
314 set, use 'none' or 'never'.
c7d32c0b 315 </p>
16fde7f0
TU
316
317 <div class="variablelist"><dl class="variablelist">
c7d32c0b 318<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
319<dd>
320 <p>
e62b9c9c
TU
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".
16fde7f0
TU
325 </p>
326 </dd>
e62b9c9c 327<dt><span class="term">-P sync <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
328<dd>
329 <p>
e62b9c9c
TU
330 Sets the date on which the CDS and CDNSKEY records which match
331 this key are to be published to the zone.
16fde7f0
TU
332 </p>
333 </dd>
c7d32c0b 334<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
335<dd>
336 <p>
e62b9c9c
TU
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".
16fde7f0
TU
341 </p>
342 </dd>
c7d32c0b 343<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
344<dd>
345 <p>
e62b9c9c
TU
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.
16fde7f0
TU
349 </p>
350 </dd>
79cf9524 351<dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
352<dd>
353 <p>
e62b9c9c
TU
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.
16fde7f0
TU
357 </p>
358 </dd>
c7d32c0b 359<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
360<dd>
361 <p>
e62b9c9c
TU
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.)
16fde7f0
TU
365 </p>
366 </dd>
e62b9c9c 367<dt><span class="term">-D sync <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
368<dd>
369 <p>
e62b9c9c
TU
370 Sets the date on which the CDS and CDNSKEY records which match
371 this key are to be deleted.
16fde7f0
TU
372 </p>
373 </dd>
794b79e6
TU
374<dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt>
375<dd>
e640ea93
TU
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>
c7d32c0b 398</dl></div>
16fde7f0
TU
399 </div>
400
401 <div class="refsection">
fd2597f7 402<a name="id-1.10"></a><h2>GENERATED KEY FILES</h2>
16fde7f0
TU
403
404 <p>
2eeb74d1 405 When <span class="command"><strong>dnssec-keyfromlabel</strong></span> completes
90f35c2f
FD
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>
16fde7f0
TU
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
e62b9c9c 418 of the algorithm.
16fde7f0
TU
419 </p>
420 </li>
421<li class="listitem">
422 <p><code class="filename">iiiii</code> is the key identifier (or
e62b9c9c 423 footprint).
16fde7f0
TU
424 </p>
425 </li>
90f35c2f 426</ul></div>
16fde7f0 427 <p><span class="command"><strong>dnssec-keyfromlabel</strong></span>
90f35c2f
FD
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
c7d32c0b 432 private key.
90f35c2f 433 </p>
16fde7f0 434 <p>
90f35c2f
FD
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>
16fde7f0 440 <p>
c7d32c0b
AU
441 The <code class="filename">.private</code> file contains
442 algorithm-specific
90f35c2f
FD
443 fields. For obvious security reasons, this file does not have
444 general read permission.
445 </p>
16fde7f0
TU
446 </div>
447
448 <div class="refsection">
fd2597f7 449<a name="id-1.11"></a><h2>SEE ALSO</h2>
16fde7f0
TU
450
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>,
90f35c2f 457 <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
bbbf2e27
TU
458 <em class="citetitle">RFC 4034</em>,
459 <em class="citetitle">The PKCS#11 URI Scheme (draft-pechanec-pkcs11uri-13)</em>.
90f35c2f 460 </p>
16fde7f0
TU
461 </div>
462
90f35c2f
FD
463</div></body>
464</html>