| blob | 193be7cd51b1f3ade224de085ad1f08690a86920 |
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 "—">]>
4 <!--
5 - Copyright (C) 2004, 2005, 2007-2012, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000-2003 Internet Software Consortium.
7 -
8 - Permission to use, copy, modify, and/or distribute this software for any
9 - purpose with or without fee is hereby granted, provided that the above
10 - copyright notice and this permission notice appear in all copies.
11 -
12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
18 - PERFORMANCE OF THIS SOFTWARE.
19 -->
21 <refentry id="man.dnssec-keygen">
22 <refentryinfo>
23 <date>February 06, 2014</date>
24 </refentryinfo>
26 <refmeta>
27 <refentrytitle><application>dnssec-keygen</application></refentrytitle>
28 <manvolnum>8</manvolnum>
29 <refmiscinfo>BIND9</refmiscinfo>
30 </refmeta>
32 <refnamediv>
33 <refname><application>dnssec-keygen</application></refname>
34 <refpurpose>DNSSEC key generation tool</refpurpose>
35 </refnamediv>
37 <docinfo>
38 <copyright>
39 <year>2004</year>
40 <year>2005</year>
41 <year>2007</year>
42 <year>2008</year>
43 <year>2009</year>
44 <year>2010</year>
45 <year>2011</year>
46 <year>2012</year>
47 <year>2014</year>
48 <year>2015</year>
49 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
50 </copyright>
51 <copyright>
52 <year>2000</year>
53 <year>2001</year>
54 <year>2002</year>
55 <year>2003</year>
56 <holder>Internet Software Consortium.</holder>
57 </copyright>
58 </docinfo>
60 <refsynopsisdiv>
61 <cmdsynopsis>
62 <command>dnssec-keygen</command>
63 <arg><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
64 <arg ><option>-b <replaceable class="parameter">keysize</replaceable></option></arg>
65 <arg><option>-n <replaceable class="parameter">nametype</replaceable></option></arg>
66 <arg><option>-3</option></arg>
67 <arg><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
68 <arg><option>-C</option></arg>
69 <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
70 <arg><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
71 <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
72 <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
73 <arg><option>-G</option></arg>
74 <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
75 <arg><option>-h</option></arg>
76 <arg><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
77 <arg><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
78 <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
79 <arg><option>-L <replaceable class="parameter">ttl</replaceable></option></arg>
80 <arg><option>-k</option></arg>
81 <arg><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
82 <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
83 <arg><option>-q</option></arg>
84 <arg><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
85 <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
86 <arg><option>-S <replaceable class="parameter">key</replaceable></option></arg>
87 <arg><option>-s <replaceable class="parameter">strength</replaceable></option></arg>
88 <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
89 <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
90 <arg><option>-V</option></arg>
91 <arg><option>-z</option></arg>
92 <arg choice="req">name</arg>
93 </cmdsynopsis>
94 </refsynopsisdiv>
96 <refsect1>
97 <title>DESCRIPTION</title>
98 <para><command>dnssec-keygen</command>
99 generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
100 and RFC 4034. It can also generate keys for use with
101 TSIG (Transaction Signatures) as defined in RFC 2845, or TKEY
102 (Transaction Key) as defined in RFC 2930.
103 </para>
104 <para>
105 The <option>name</option> of the key is specified on the command
106 line. For DNSSEC keys, this must match the name of the zone for
107 which the key is being generated.
108 </para>
109 </refsect1>
111 <refsect1>
112 <title>OPTIONS</title>
114 <variablelist>
115 <varlistentry>
116 <term>-a <replaceable class="parameter">algorithm</replaceable></term>
117 <listitem>
118 <para>
119 Selects the cryptographic algorithm. For DNSSEC keys, the value
120 of <option>algorithm</option> must be one of RSAMD5, RSASHA1,
121 DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512, ECCGOST,
122 ECDSAP256SHA256 or ECDSAP384SHA384.
123 For TSIG/TKEY, the value must
124 be DH (Diffie Hellman), HMAC-MD5, HMAC-SHA1, HMAC-SHA224,
125 HMAC-SHA256, HMAC-SHA384, or HMAC-SHA512. These values are
126 case insensitive.
127 </para>
128 <para>
129 If no algorithm is specified, then RSASHA1 will be used by
130 default, unless the <option>-3</option> option is specified,
131 in which case NSEC3RSASHA1 will be used instead. (If
132 <option>-3</option> is used and an algorithm is specified,
133 that algorithm will be checked for compatibility with NSEC3.)
134 </para>
135 <para>
136 Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
137 algorithm, and DSA is recommended. For TSIG, HMAC-MD5 is
138 mandatory.
139 </para>
140 <para>
141 Note 2: DH, HMAC-MD5, and HMAC-SHA1 through HMAC-SHA512
142 automatically set the -T KEY option.
143 </para>
144 </listitem>
145 </varlistentry>
147 <varlistentry>
148 <term>-b <replaceable class="parameter">keysize</replaceable></term>
149 <listitem>
150 <para>
151 Specifies the number of bits in the key. The choice of key
152 size depends on the algorithm used. RSA keys must be
153 between 512 and 2048 bits. Diffie Hellman keys must be between
154 128 and 4096 bits. DSA keys must be between 512 and 1024
155 bits and an exact multiple of 64. HMAC keys must be
156 between 1 and 512 bits. Elliptic curve algorithms don't need
157 this parameter.
158 </para>
159 <para>
160 The key size does not need to be specified if using a default
161 algorithm. The default key size is 1024 bits for zone signing
162 keys (ZSK's) and 2048 bits for key signing keys (KSK's,
163 generated with <option>-f KSK</option>). However, if an
164 algorithm is explicitly specified with the <option>-a</option>,
165 then there is no default key size, and the <option>-b</option>
166 must be used.
167 </para>
168 </listitem>
169 </varlistentry>
171 <varlistentry>
172 <term>-n <replaceable class="parameter">nametype</replaceable></term>
173 <listitem>
174 <para>
175 Specifies the owner type of the key. The value of
176 <option>nametype</option> 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. Defaults to ZONE for DNSKEY
181 generation.
182 </para>
183 </listitem>
184 </varlistentry>
186 <varlistentry>
187 <term>-3</term>
188 <listitem>
189 <para>
190 Use an NSEC3-capable algorithm to generate a DNSSEC key.
191 If this option is used and no algorithm is explicitly
192 set on the command line, NSEC3RSASHA1 will be used by
193 default. Note that RSASHA256, RSASHA512, ECCGOST,
194 ECDSAP256SHA256 and ECDSAP384SHA384 algorithms
195 are NSEC3-capable.
196 </para>
197 </listitem>
198 </varlistentry>
200 <varlistentry>
201 <term>-C</term>
202 <listitem>
203 <para>
204 Compatibility mode: generates an old-style key, without
205 any metadata. By default, <command>dnssec-keygen</command>
206 will include the key's creation date in the metadata stored
207 with the private key, and other dates may be set there as well
208 (publication date, activation date, etc). Keys that include
209 this data may be incompatible with older versions of BIND; the
210 <option>-C</option> option suppresses them.
211 </para>
212 </listitem>
213 </varlistentry>
215 <varlistentry>
216 <term>-c <replaceable class="parameter">class</replaceable></term>
217 <listitem>
218 <para>
219 Indicates that the DNS record containing the key should have
220 the specified class. If not specified, class IN is used.
221 </para>
222 </listitem>
223 </varlistentry>
225 <varlistentry>
226 <term>-E <replaceable class="parameter">engine</replaceable></term>
227 <listitem>
228 <para>
229 Specifies the cryptographic hardware to use, when applicable.
230 </para>
231 <para>
232 When BIND is built with OpenSSL PKCS#11 support, this defaults
233 to the string "pkcs11", which identifies an OpenSSL engine
234 that can drive a cryptographic accelerator or hardware service
235 module. When BIND is built with native PKCS#11 cryptography
236 (--enable-native-pkcs11), it defaults to the path of the PKCS#11
237 provider library specified via "--with-pkcs11".
238 </para>
239 </listitem>
240 </varlistentry>
242 <varlistentry>
243 <term>-f <replaceable class="parameter">flag</replaceable></term>
244 <listitem>
245 <para>
246 Set the specified flag in the flag field of the KEY/DNSKEY record.
247 The only recognized flags are KSK (Key Signing Key) and REVOKE.
248 </para>
249 </listitem>
250 </varlistentry>
252 <varlistentry>
253 <term>-G</term>
254 <listitem>
255 <para>
256 Generate a key, but do not publish it or sign with it. This
257 option is incompatible with -P and -A.
258 </para>
259 </listitem>
260 </varlistentry>
262 <varlistentry>
263 <term>-g <replaceable class="parameter">generator</replaceable></term>
264 <listitem>
265 <para>
266 If generating a Diffie Hellman key, use this generator.
267 Allowed values are 2 and 5. If no generator
268 is specified, a known prime from RFC 2539 will be used
269 if possible; otherwise the default is 2.
270 </para>
271 </listitem>
272 </varlistentry>
274 <varlistentry>
275 <term>-h</term>
276 <listitem>
277 <para>
278 Prints a short summary of the options and arguments to
279 <command>dnssec-keygen</command>.
280 </para>
281 </listitem>
282 </varlistentry>
284 <varlistentry>
285 <term>-K <replaceable class="parameter">directory</replaceable></term>
286 <listitem>
287 <para>
288 Sets the directory in which the key files are to be written.
289 </para>
290 </listitem>
291 </varlistentry>
293 <varlistentry>
294 <term>-k</term>
295 <listitem>
296 <para>
297 Deprecated in favor of -T KEY.
298 </para>
299 </listitem>
300 </varlistentry>
302 <varlistentry>
303 <term>-L <replaceable class="parameter">ttl</replaceable></term>
304 <listitem>
305 <para>
306 Sets the default TTL to use for this key when it is converted
307 into a DNSKEY RR. If the key is imported into a zone,
308 this is the TTL that will be used for it, unless there was
309 already a DNSKEY RRset in place, in which case the existing TTL
310 would take precedence. If this value is not set and there
311 is no existing DNSKEY RRset, the TTL will default to the
312 SOA TTL. Setting the default TTL to <literal>0</literal>
313 or <literal>none</literal> is the same as leaving it unset.
314 </para>
315 </listitem>
316 </varlistentry>
318 <varlistentry>
319 <term>-p <replaceable class="parameter">protocol</replaceable></term>
320 <listitem>
321 <para>
322 Sets the protocol value for the generated key. The protocol
323 is a number between 0 and 255. The default is 3 (DNSSEC).
324 Other possible values for this argument are listed in
325 RFC 2535 and its successors.
326 </para>
327 </listitem>
328 </varlistentry>
330 <varlistentry>
331 <term>-q</term>
332 <listitem>
333 <para>
334 Quiet mode: Suppresses unnecessary output, including
335 progress indication. Without this option, when
336 <command>dnssec-keygen</command> is run interactively
337 to generate an RSA or DSA key pair, it will print a string
338 of symbols to <filename>stderr</filename> indicating the
339 progress of the key generation. A '.' indicates that a
340 random number has been found which passed an initial
341 sieve test; '+' means a number has passed a single
342 round of the Miller-Rabin primality test; a space
343 means that the number has passed all the tests and is
344 a satisfactory key.
345 </para>
346 </listitem>
347 </varlistentry>
349 <varlistentry>
350 <term>-r <replaceable class="parameter">randomdev</replaceable></term>
351 <listitem>
352 <para>
353 Specifies the source of randomness. If the operating
354 system does not provide a <filename>/dev/random</filename>
355 or equivalent device, the default source of randomness
356 is keyboard input. <filename>randomdev</filename>
357 specifies
358 the name of a character device or file containing random
359 data to be used instead of the default. The special value
360 <filename>keyboard</filename> indicates that keyboard
361 input should be used.
362 </para>
363 </listitem>
364 </varlistentry>
366 <varlistentry>
367 <term>-S <replaceable class="parameter">key</replaceable></term>
368 <listitem>
369 <para>
370 Create a new key which is an explicit successor to an
371 existing key. The name, algorithm, size, and type of the
372 key will be set to match the existing key. The activation
373 date of the new key will be set to the inactivation date of
374 the existing one. The publication date will be set to the
375 activation date minus the prepublication interval, which
376 defaults to 30 days.
377 </para>
378 </listitem>
379 </varlistentry>
381 <varlistentry>
382 <term>-s <replaceable class="parameter">strength</replaceable></term>
383 <listitem>
384 <para>
385 Specifies the strength value of the key. The strength is
386 a number between 0 and 15, and currently has no defined
387 purpose in DNSSEC.
388 </para>
389 </listitem>
390 </varlistentry>
392 <varlistentry>
393 <term>-T <replaceable class="parameter">rrtype</replaceable></term>
394 <listitem>
395 <para>
396 Specifies the resource record type to use for the key.
397 <option>rrtype</option> must be either DNSKEY or KEY. The
398 default is DNSKEY when using a DNSSEC algorithm, but it can be
399 overridden to KEY for use with SIG(0).
400 <para>
401 </para>
402 Using any TSIG algorithm (HMAC-* or DH) forces this option
403 to KEY.
404 </para>
405 </listitem>
406 </varlistentry>
408 <varlistentry>
409 <term>-t <replaceable class="parameter">type</replaceable></term>
410 <listitem>
411 <para>
412 Indicates the use of the key. <option>type</option> must be
413 one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
414 is AUTHCONF. AUTH refers to the ability to authenticate
415 data, and CONF the ability to encrypt data.
416 </para>
417 </listitem>
418 </varlistentry>
420 <varlistentry>
421 <term>-v <replaceable class="parameter">level</replaceable></term>
422 <listitem>
423 <para>
424 Sets the debugging level.
425 </para>
426 </listitem>
427 </varlistentry>
429 <varlistentry>
430 <term>-V</term>
431 <listitem>
432 <para>
433 Prints version information.
434 </para>
435 </listitem>
436 </varlistentry>
438 </variablelist>
439 </refsect1>
441 <refsect1>
442 <title>TIMING OPTIONS</title>
444 <para>
445 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
446 If the argument begins with a '+' or '-', it is interpreted as
447 an offset from the present time. For convenience, if such an offset
448 is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
449 then the offset is computed in years (defined as 365 24-hour days,
450 ignoring leap years), months (defined as 30 24-hour days), weeks,
451 days, hours, or minutes, respectively. Without a suffix, the offset
452 is computed in seconds. To explicitly prevent a date from being
453 set, use 'none' or 'never'.
454 </para>
456 <variablelist>
457 <varlistentry>
458 <term>-P <replaceable class="parameter">date/offset</replaceable></term>
459 <listitem>
460 <para>
461 Sets the date on which a key is to be published to the zone.
462 After that date, the key will be included in the zone but will
463 not be used to sign it. If not set, and if the -G option has
464 not been used, the default is "now".
465 </para>
466 </listitem>
467 </varlistentry>
469 <varlistentry>
470 <term>-A <replaceable class="parameter">date/offset</replaceable></term>
471 <listitem>
472 <para>
473 Sets the date on which the key is to be activated. After that
474 date, the key will be included in the zone and used to sign
475 it. If not set, and if the -G option has not been used, the
476 default is "now". If set, if and -P is not set, then
477 the publication date will be set to the activation date
478 minus the prepublication interval.
479 </para>
480 </listitem>
481 </varlistentry>
483 <varlistentry>
484 <term>-R <replaceable class="parameter">date/offset</replaceable></term>
485 <listitem>
486 <para>
487 Sets the date on which the key is to be revoked. After that
488 date, the key will be flagged as revoked. It will be included
489 in the zone and will be used to sign it.
490 </para>
491 </listitem>
492 </varlistentry>
494 <varlistentry>
495 <term>-I <replaceable class="parameter">date/offset</replaceable></term>
496 <listitem>
497 <para>
498 Sets the date on which the key is to be retired. After that
499 date, the key will still be included in the zone, but it
500 will not be used to sign it.
501 </para>
502 </listitem>
503 </varlistentry>
505 <varlistentry>
506 <term>-D <replaceable class="parameter">date/offset</replaceable></term>
507 <listitem>
508 <para>
509 Sets the date on which the key is to be deleted. After that
510 date, the key will no longer be included in the zone. (It
511 may remain in the key repository, however.)
512 </para>
513 </listitem>
514 </varlistentry>
516 <varlistentry>
517 <term>-i <replaceable class="parameter">interval</replaceable></term>
518 <listitem>
519 <para>
520 Sets the prepublication interval for a key. If set, then
521 the publication and activation dates must be separated by at least
522 this much time. If the activation date is specified but the
523 publication date isn't, then the publication date will default
524 to this much time before the activation date; conversely, if
525 the publication date is specified but activation date isn't,
526 then activation will be set to this much time after publication.
527 </para>
528 <para>
529 If the key is being created as an explicit successor to another
530 key, then the default prepublication interval is 30 days;
531 otherwise it is zero.
532 </para>
533 <para>
534 As with date offsets, if the argument is followed by one of
535 the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
536 interval is measured in years, months, weeks, days, hours,
537 or minutes, respectively. Without a suffix, the interval is
538 measured in seconds.
539 </para>
540 </listitem>
541 </varlistentry>
543 </variablelist>
544 </refsect1>
547 <refsect1>
548 <title>GENERATED KEYS</title>
549 <para>
550 When <command>dnssec-keygen</command> completes
551 successfully,
552 it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
553 to the standard output. This is an identification string for
554 the key it has generated.
555 </para>
556 <itemizedlist>
557 <listitem>
558 <para><filename>nnnn</filename> is the key name.
559 </para>
560 </listitem>
561 <listitem>
562 <para><filename>aaa</filename> is the numeric representation
563 of the
564 algorithm.
565 </para>
566 </listitem>
567 <listitem>
568 <para><filename>iiiii</filename> is the key identifier (or
569 footprint).
570 </para>
571 </listitem>
572 </itemizedlist>
573 <para><command>dnssec-keygen</command>
574 creates two files, with names based
575 on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
576 contains the public key, and
577 <filename>Knnnn.+aaa+iiiii.private</filename> contains the
578 private
579 key.
580 </para>
581 <para>
582 The <filename>.key</filename> file contains a DNS KEY record
583 that
584 can be inserted into a zone file (directly or with a $INCLUDE
585 statement).
586 </para>
587 <para>
588 The <filename>.private</filename> file contains
589 algorithm-specific
590 fields. For obvious security reasons, this file does not have
591 general read permission.
592 </para>
593 <para>
594 Both <filename>.key</filename> and <filename>.private</filename>
595 files are generated for symmetric encryption algorithms such as
596 HMAC-MD5, even though the public and private key are equivalent.
597 </para>
598 </refsect1>
600 <refsect1>
601 <title>EXAMPLE</title>
602 <para>
603 To generate a 768-bit DSA key for the domain
604 <userinput>example.com</userinput>, the following command would be
605 issued:
606 </para>
607 <para><userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
608 </para>
609 <para>
610 The command would print a string of the form:
611 </para>
612 <para><userinput>Kexample.com.+003+26160</userinput>
613 </para>
614 <para>
615 In this example, <command>dnssec-keygen</command> creates
616 the files <filename>Kexample.com.+003+26160.key</filename>
617 and
618 <filename>Kexample.com.+003+26160.private</filename>.
619 </para>
620 </refsect1>
622 <refsect1>
623 <title>SEE ALSO</title>
624 <para><citerefentry>
625 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
626 </citerefentry>,
627 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
628 <citetitle>RFC 2539</citetitle>,
629 <citetitle>RFC 2845</citetitle>,
630 <citetitle>RFC 4034</citetitle>.
631 </para>
632 </refsect1>
634 <refsect1>
635 <title>AUTHOR</title>
636 <para><corpauthor>Internet Systems Consortium</corpauthor>
637 </para>
638 </refsect1>
640 </refentry><!--
641 - Local variables:
642 - mode: sgml
643 - End:
644 -->