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