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--> 20 21<refentry id="man.dnssec-keygen"> 22 <refentryinfo> 23 <date>February 06, 2014</date> 24 </refentryinfo> 25 26 <refmeta> 27 <refentrytitle><application>dnssec-keygen</application></refentrytitle> 28 <manvolnum>8</manvolnum> 29 <refmiscinfo>BIND9</refmiscinfo> 30 </refmeta> 31 32 <refnamediv> 33 <refname><application>dnssec-keygen</application></refname> 34 <refpurpose>DNSSEC key generation tool</refpurpose> 35 </refnamediv> 36 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> 59 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> 95 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> 110 111 <refsect1> 112 <title>OPTIONS</title> 113 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> 146 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> 170 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> 185 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> 199 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> 214 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> 224 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> 241 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> 251 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> 261 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> 273 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> 283 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> 292 293 <varlistentry> 294 <term>-k</term> 295 <listitem> 296 <para> 297 Deprecated in favor of -T KEY. 298 </para> 299 </listitem> 300 </varlistentry> 301 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> 317 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> 329 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> 348 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> 365 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> 380 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> 391 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> 407 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> 419 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> 428 429 <varlistentry> 430 <term>-V</term> 431 <listitem> 432 <para> 433 Prints version information. 434 </para> 435 </listitem> 436 </varlistentry> 437 438 </variablelist> 439 </refsect1> 440 441 <refsect1> 442 <title>TIMING OPTIONS</title> 443 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> 455 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> 468 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> 482 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> 493 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> 504 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> 515 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> 542 543 </variablelist> 544 </refsect1> 545 546 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> 599 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> 621 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> 633 634 <refsect1> 635 <title>AUTHOR</title> 636 <para><corpauthor>Internet Systems Consortium</corpauthor> 637 </para> 638 </refsect1> 639 640</refentry><!-- 641 - Local variables: 642 - mode: sgml 643 - End: 644--> 645