1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3 [<!ENTITY mdash "—">]>
5 - Copyright (C) 2008-2011 Internet Systems Consortium, Inc. ("ISC")
7 - Permission to use, copy, modify, and/or distribute this software for any
8 - purpose with or without fee is hereby granted, provided that the above
9 - copyright notice and this permission notice appear in all copies.
11 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17 - PERFORMANCE OF THIS SOFTWARE.
20 <!-- $Id: dnssec-keyfromlabel.docbook,v 1.18.14.2 2011-02-28 01:19:58 tbox Exp $ -->
21 <refentry id="man.dnssec-keyfromlabel">
23 <date>February 8, 2008</date>
27 <refentrytitle><application>dnssec-keyfromlabel</application></refentrytitle>
28 <manvolnum>8</manvolnum>
29 <refmiscinfo>BIND9</refmiscinfo>
33 <refname><application>dnssec-keyfromlabel</application></refname>
34 <refpurpose>DNSSEC key generation tool</refpurpose>
43 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
49 <command>dnssec-keyfromlabel</command>
50 <arg choice="req">-l <replaceable class="parameter">label</replaceable></arg>
51 <arg><option>-3</option></arg>
52 <arg><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
53 <arg><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
54 <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
55 <arg><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
56 <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
57 <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
58 <arg><option>-G</option></arg>
59 <arg><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
60 <arg><option>-k</option></arg>
61 <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
62 <arg><option>-n <replaceable class="parameter">nametype</replaceable></option></arg>
63 <arg><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
64 <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
65 <arg><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
66 <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
67 <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
68 <arg><option>-y</option></arg>
69 <arg choice="req">name</arg>
74 <title>DESCRIPTION</title>
75 <para><command>dnssec-keyfromlabel</command>
76 gets keys with the given label from a crypto hardware and builds
77 key files for DNSSEC (Secure DNS), as defined in RFC 2535
81 The <option>name</option> of the key is specified on the command
82 line. This must match the name of the zone for which the key is
88 <title>OPTIONS</title>
92 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
95 Selects the cryptographic algorithm. The value of
96 <option>algorithm</option> must be one of RSAMD5, RSASHA1,
97 DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512 or ECCGOST.
98 These values are case insensitive.
101 If no algorithm is specified, then RSASHA1 will be used by
102 default, unless the <option>-3</option> option is specified,
103 in which case NSEC3RSASHA1 will be used instead. (If
104 <option>-3</option> is used and an algorithm is specified,
105 that algorithm will be checked for compatibility with NSEC3.)
108 Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
109 algorithm, and DSA is recommended.
112 Note 2: DH automatically sets the -k flag.
121 Use an NSEC3-capable algorithm to generate a DNSSEC key.
122 If this option is used and no algorithm is explicitly
123 set on the command line, NSEC3RSASHA1 will be used by
130 <term>-E <replaceable class="parameter">engine</replaceable></term>
133 Specifies the name of the crypto hardware (OpenSSL engine).
134 When compiled with PKCS#11 support it defaults to "pkcs11".
140 <term>-l <replaceable class="parameter">label</replaceable></term>
143 Specifies the label of the key pair in the crypto hardware.
144 The label may be preceded by an optional OpenSSL engine name,
145 separated by a colon, as in "pkcs11:keylabel".
151 <term>-n <replaceable class="parameter">nametype</replaceable></term>
154 Specifies the owner type of the key. The value of
155 <option>nametype</option> must either be ZONE (for a DNSSEC
156 zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
158 USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
159 These values are case insensitive.
168 Compatibility mode: generates an old-style key, without
169 any metadata. By default, <command>dnssec-keyfromlabel</command>
170 will include the key's creation date in the metadata stored
171 with the private key, and other dates may be set there as well
172 (publication date, activation date, etc). Keys that include
173 this data may be incompatible with older versions of BIND; the
174 <option>-C</option> option suppresses them.
180 <term>-c <replaceable class="parameter">class</replaceable></term>
183 Indicates that the DNS record containing the key should have
184 the specified class. If not specified, class IN is used.
190 <term>-f <replaceable class="parameter">flag</replaceable></term>
193 Set the specified flag in the flag field of the KEY/DNSKEY record.
194 The only recognized flags are KSK (Key Signing Key) and REVOKE.
203 Generate a key, but do not publish it or sign with it. This
204 option is incompatible with -P and -A.
213 Prints a short summary of the options and arguments to
214 <command>dnssec-keyfromlabel</command>.
220 <term>-K <replaceable class="parameter">directory</replaceable></term>
223 Sets the directory in which the key files are to be written.
232 Generate KEY records rather than DNSKEY records.
238 <term>-p <replaceable class="parameter">protocol</replaceable></term>
241 Sets the protocol value for the key. The protocol
242 is a number between 0 and 255. The default is 3 (DNSSEC).
243 Other possible values for this argument are listed in
244 RFC 2535 and its successors.
250 <term>-t <replaceable class="parameter">type</replaceable></term>
253 Indicates the use of the key. <option>type</option> must be
254 one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
255 is AUTHCONF. AUTH refers to the ability to authenticate
256 data, and CONF the ability to encrypt data.
262 <term>-v <replaceable class="parameter">level</replaceable></term>
265 Sets the debugging level.
274 Allows DNSSEC key files to be generated even if the key ID
275 would collide with that of an existing key, in the event of
276 either key being revoked. (This is only safe to use if you
277 are sure you won't be using RFC 5011 trust anchor maintenance
278 with either of the keys involved.)
287 <title>TIMING OPTIONS</title>
290 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
291 If the argument begins with a '+' or '-', it is interpreted as
292 an offset from the present time. For convenience, if such an offset
293 is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
294 then the offset is computed in years (defined as 365 24-hour days,
295 ignoring leap years), months (defined as 30 24-hour days), weeks,
296 days, hours, or minutes, respectively. Without a suffix, the offset
297 is computed in seconds.
302 <term>-P <replaceable class="parameter">date/offset</replaceable></term>
305 Sets the date on which a key is to be published to the zone.
306 After that date, the key will be included in the zone but will
307 not be used to sign it. If not set, and if the -G option has
308 not been used, the default is "now".
314 <term>-A <replaceable class="parameter">date/offset</replaceable></term>
317 Sets the date on which the key is to be activated. After that
318 date, the key will be included in the zone and used to sign
319 it. If not set, and if the -G option has not been used, the
326 <term>-R <replaceable class="parameter">date/offset</replaceable></term>
329 Sets the date on which the key is to be revoked. After that
330 date, the key will be flagged as revoked. It will be included
331 in the zone and will be used to sign it.
337 <term>-I <replaceable class="parameter">date/offset</replaceable></term>
340 Sets the date on which the key is to be retired. After that
341 date, the key will still be included in the zone, but it
342 will not be used to sign it.
348 <term>-D <replaceable class="parameter">date/offset</replaceable></term>
351 Sets the date on which the key is to be deleted. After that
352 date, the key will no longer be included in the zone. (It
353 may remain in the key repository, however.)
361 <title>GENERATED KEY FILES</title>
363 When <command>dnssec-keyfromlabel</command> completes
365 it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
366 to the standard output. This is an identification string for
367 the key files it has generated.
371 <para><filename>nnnn</filename> is the key name.
375 <para><filename>aaa</filename> is the numeric representation
380 <para><filename>iiiii</filename> is the key identifier (or
385 <para><command>dnssec-keyfromlabel</command>
386 creates two files, with names based
387 on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
388 contains the public key, and
389 <filename>Knnnn.+aaa+iiiii.private</filename> contains the
393 The <filename>.key</filename> file contains a DNS KEY record
395 can be inserted into a zone file (directly or with a $INCLUDE
399 The <filename>.private</filename> file contains
401 fields. For obvious security reasons, this file does not have
402 general read permission.
407 <title>SEE ALSO</title>
409 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
412 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
414 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
415 <citetitle>RFC 4034</citetitle>.
420 <title>AUTHOR</title>
421 <para><corpauthor>Internet Systems Consortium</corpauthor>