2 - Copyright (C) 2008-2012, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
4 - Permission to use, copy, modify, and/or distribute this software for any
5 - purpose with or without fee is hereby granted, provided that the above
6 - copyright notice and this permission notice appear in all copies.
8 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
11 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
13 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14 - PERFORMANCE OF THIS SOFTWARE.
17 <!-- Converted by db4-upgrade version 1.0 -->
18 <refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="man.dnssec-keyfromlabel">
20 <date>2014-02-27</date>
23 <corpname>ISC</corpname>
24 <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
28 <refentrytitle><application>dnssec-keyfromlabel</application></refentrytitle>
29 <manvolnum>8</manvolnum>
30 <refmiscinfo>BIND9</refmiscinfo>
34 <refname><application>dnssec-keyfromlabel</application></refname>
35 <refpurpose>DNSSEC key generation tool</refpurpose>
47 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
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>-E <replaceable class="parameter">engine</replaceable></option></arg>
61 <arg choice="opt" rep="norepeat"><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
62 <arg choice="opt" rep="norepeat"><option>-G</option></arg>
63 <arg choice="opt" rep="norepeat"><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
64 <arg choice="opt" rep="norepeat"><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
65 <arg choice="opt" rep="norepeat"><option>-k</option></arg>
66 <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
67 <arg choice="opt" rep="norepeat"><option>-L <replaceable class="parameter">ttl</replaceable></option></arg>
68 <arg choice="opt" rep="norepeat"><option>-n <replaceable class="parameter">nametype</replaceable></option></arg>
69 <arg choice="opt" rep="norepeat"><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
70 <arg choice="opt" rep="norepeat"><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
71 <arg choice="opt" rep="norepeat"><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
72 <arg choice="opt" rep="norepeat"><option>-S <replaceable class="parameter">key</replaceable></option></arg>
73 <arg choice="opt" rep="norepeat"><option>-t <replaceable class="parameter">type</replaceable></option></arg>
74 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
75 <arg choice="opt" rep="norepeat"><option>-V</option></arg>
76 <arg choice="opt" rep="norepeat"><option>-y</option></arg>
77 <arg choice="req" rep="norepeat">name</arg>
81 <refsection><info><title>DESCRIPTION</title></info>
83 <para><command>dnssec-keyfromlabel</command>
84 generates a key pair of files that referencing a key object stored
85 in a cryptographic hardware service module (HSM). The private key
86 file can be used for DNSSEC signing of zone data as if it were a
87 conventional signing key created by <command>dnssec-keygen</command>,
88 but the key material is stored within the HSM, and the actual signing
92 The <option>name</option> of the key is specified on the command
93 line. This must match the name of the zone for which the key is
98 <refsection><info><title>OPTIONS</title></info>
103 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
106 Selects the cryptographic algorithm. The value of
107 <option>algorithm</option> must be one of RSAMD5, RSASHA1,
108 DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512, ECCGOST,
109 ECDSAP256SHA256 or ECDSAP384SHA384.
110 These values are case insensitive.
113 If no algorithm is specified, then RSASHA1 will be used by
114 default, unless the <option>-3</option> option is specified,
115 in which case NSEC3RSASHA1 will be used instead. (If
116 <option>-3</option> is used and an algorithm is specified,
117 that algorithm will be checked for compatibility with NSEC3.)
120 Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
121 algorithm, and DSA is recommended.
124 Note 2: DH automatically sets the -k flag.
133 Use an NSEC3-capable algorithm to generate a DNSSEC key.
134 If this option is used and no algorithm is explicitly
135 set on the command line, NSEC3RSASHA1 will be used by
142 <term>-E <replaceable class="parameter">engine</replaceable></term>
145 Specifies the name of the crypto hardware (OpenSSL engine).
146 When compiled with PKCS#11 support it defaults to "pkcs11".
152 <term>-l <replaceable class="parameter">label</replaceable></term>
155 Specifies the label of the key pair in the crypto hardware.
156 The label may be preceded by an optional OpenSSL engine name,
157 separated by a colon, as in "pkcs11:keylabel".
163 <term>-n <replaceable class="parameter">nametype</replaceable></term>
166 Specifies the owner type of the key. The value of
167 <option>nametype</option> must either be ZONE (for a DNSSEC
168 zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
170 USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
171 These values are case insensitive.
180 Compatibility mode: generates an old-style key, without
181 any metadata. By default, <command>dnssec-keyfromlabel</command>
182 will include the key's creation date in the metadata stored
183 with the private key, and other dates may be set there as well
184 (publication date, activation date, etc). Keys that include
185 this data may be incompatible with older versions of BIND; the
186 <option>-C</option> option suppresses them.
192 <term>-c <replaceable class="parameter">class</replaceable></term>
195 Indicates that the DNS record containing the key should have
196 the specified class. If not specified, class IN is used.
202 <term>-f <replaceable class="parameter">flag</replaceable></term>
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.
215 Generate a key, but do not publish it or sign with it. This
216 option is incompatible with -P and -A.
225 Prints a short summary of the options and arguments to
226 <command>dnssec-keyfromlabel</command>.
232 <term>-K <replaceable class="parameter">directory</replaceable></term>
235 Sets the directory in which the key files are to be written.
244 Generate KEY records rather than DNSKEY records.
250 <term>-L <replaceable class="parameter">ttl</replaceable></term>
253 Sets the default TTL to use for this key when it is converted
254 into a DNSKEY RR. If the key is imported into a zone,
255 this is the TTL that will be used for it, unless there was
256 already a DNSKEY RRset in place, in which case the existing TTL
257 would take precedence. Setting the default TTL to
258 <literal>0</literal> or <literal>none</literal> removes it.
264 <term>-p <replaceable class="parameter">protocol</replaceable></term>
267 Sets the protocol value for the key. The protocol
268 is a number between 0 and 255. The default is 3 (DNSSEC).
269 Other possible values for this argument are listed in
270 RFC 2535 and its successors.
276 <term>-S <replaceable class="parameter">key</replaceable></term>
279 Generate a key as an explicit successor to an existing key.
280 The name, algorithm, size, and type of the key will be set
281 to match the predecessor. The activation date of the new
282 key will be set to the inactivation date of the existing
283 one. The publication date will be set to the activation
284 date minus the prepublication interval, which defaults to
291 <term>-t <replaceable class="parameter">type</replaceable></term>
294 Indicates the use of the key. <option>type</option> must be
295 one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
296 is AUTHCONF. AUTH refers to the ability to authenticate
297 data, and CONF the ability to encrypt data.
303 <term>-v <replaceable class="parameter">level</replaceable></term>
306 Sets the debugging level.
315 Prints version information.
324 Allows DNSSEC key files to be generated even if the key ID
325 would collide with that of an existing key, in the event of
326 either key being revoked. (This is only safe to use if you
327 are sure you won't be using RFC 5011 trust anchor maintenance
328 with either of the keys involved.)
336 <refsection><info><title>TIMING OPTIONS</title></info>
340 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
341 If the argument begins with a '+' or '-', it is interpreted as
342 an offset from the present time. For convenience, if such an offset
343 is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
344 then the offset is computed in years (defined as 365 24-hour days,
345 ignoring leap years), months (defined as 30 24-hour days), weeks,
346 days, hours, or minutes, respectively. Without a suffix, the offset
347 is computed in seconds. To explicitly prevent a date from being
348 set, use 'none' or 'never'.
353 <term>-P <replaceable class="parameter">date/offset</replaceable></term>
356 Sets the date on which a key is to be published to the zone.
357 After that date, the key will be included in the zone but will
358 not be used to sign it. If not set, and if the -G option has
359 not been used, the default is "now".
365 <term>-A <replaceable class="parameter">date/offset</replaceable></term>
368 Sets the date on which the key is to be activated. After that
369 date, the key will be included in the zone and used to sign
370 it. If not set, and if the -G option has not been used, the
377 <term>-R <replaceable class="parameter">date/offset</replaceable></term>
380 Sets the date on which the key is to be revoked. After that
381 date, the key will be flagged as revoked. It will be included
382 in the zone and will be used to sign it.
388 <term>-I <replaceable class="parameter">date/offset</replaceable></term>
391 Sets the date on which the key is to be retired. After that
392 date, the key will still be included in the zone, but it
393 will not be used to sign it.
399 <term>-D <replaceable class="parameter">date/offset</replaceable></term>
402 Sets the date on which the key is to be deleted. After that
403 date, the key will no longer be included in the zone. (It
404 may remain in the key repository, however.)
410 <term>-i <replaceable class="parameter">interval</replaceable></term>
413 Sets the prepublication interval for a key. If set, then
414 the publication and activation dates must be separated by at least
415 this much time. If the activation date is specified but the
416 publication date isn't, then the publication date will default
417 to this much time before the activation date; conversely, if
418 the publication date is specified but activation date isn't,
419 then activation will be set to this much time after publication.
422 If the key is being created as an explicit successor to another
423 key, then the default prepublication interval is 30 days;
424 otherwise it is zero.
427 As with date offsets, if the argument is followed by one of
428 the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
429 interval is measured in years, months, weeks, days, hours,
430 or minutes, respectively. Without a suffix, the interval is
439 <refsection><info><title>GENERATED KEY FILES</title></info>
442 When <command>dnssec-keyfromlabel</command> completes
444 it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
445 to the standard output. This is an identification string for
446 the key files it has generated.
450 <para><filename>nnnn</filename> is the key name.
454 <para><filename>aaa</filename> is the numeric representation
459 <para><filename>iiiii</filename> is the key identifier (or
464 <para><command>dnssec-keyfromlabel</command>
465 creates two files, with names based
466 on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
467 contains the public key, and
468 <filename>Knnnn.+aaa+iiiii.private</filename> contains the
472 The <filename>.key</filename> file contains a DNS KEY record
474 can be inserted into a zone file (directly or with a $INCLUDE
478 The <filename>.private</filename> file contains
480 fields. For obvious security reasons, this file does not have
481 general read permission.
485 <refsection><info><title>SEE ALSO</title></info>
488 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
491 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
493 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
494 <citetitle>RFC 4034</citetitle>.