contrib/bind-9.2.4rc7/bin/dnssec/dnssec-keygen.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17
  18 <!-- $Id: dnssec-keygen.html,v 1.5.2.3 2004/06/03 05:21:10 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >dnssec-keygen</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 ><SPAN
  39 CLASS="APPLICATION"
  40 >dnssec-keygen</SPAN
  41 ></A
  42 ></H1
  43 ><DIV
  44 CLASS="REFNAMEDIV"
  45 ><A
  46 NAME="AEN9"
  47 ></A
  48 ><H2
  49 >Name</H2
  50 ><SPAN
  51 CLASS="APPLICATION"
  52 >dnssec-keygen</SPAN
  53 >&nbsp;--&nbsp;DNSSEC key generation tool</DIV
  54 ><DIV
  55 CLASS="REFSYNOPSISDIV"
  56 ><A
  57 NAME="AEN13"
  58 ></A
  59 ><H2
  60 >Synopsis</H2
  61 ><P
  62 ><B
  63 CLASS="COMMAND"
  64 >dnssec-keygen</B
  65 >  {-a <TT
  66 CLASS="REPLACEABLE"
  67 ><I
  68 >algorithm</I
  69 ></TT
  70 >} {-b <TT
  71 CLASS="REPLACEABLE"
  72 ><I
  73 >keysize</I
  74 ></TT
  75 >} {-n <TT
  76 CLASS="REPLACEABLE"
  77 ><I
  78 >nametype</I
  79 ></TT
  80 >} [<TT
  81 CLASS="OPTION"
  82 >-c <TT
  83 CLASS="REPLACEABLE"
  84 ><I
  85 >class</I
  86 ></TT
  87 ></TT
  88 >] [<TT
  89 CLASS="OPTION"
  90 >-e</TT
  91 >] [<TT
  92 CLASS="OPTION"
  93 >-g <TT
  94 CLASS="REPLACEABLE"
  95 ><I
  96 >generator</I
  97 ></TT
  98 ></TT
  99 >] [<TT
 100 CLASS="OPTION"
 101 >-h</TT
 102 >] [<TT
 103 CLASS="OPTION"
 104 >-p <TT
 105 CLASS="REPLACEABLE"
 106 ><I
 107 >protocol</I
 108 ></TT
 109 ></TT
 110 >] [<TT
 111 CLASS="OPTION"
 112 >-r <TT
 113 CLASS="REPLACEABLE"
 114 ><I
 115 >randomdev</I
 116 ></TT
 117 ></TT
 118 >] [<TT
 119 CLASS="OPTION"
 120 >-s <TT
 121 CLASS="REPLACEABLE"
 122 ><I
 123 >strength</I
 124 ></TT
 125 ></TT
 126 >] [<TT
 127 CLASS="OPTION"
 128 >-t <TT
 129 CLASS="REPLACEABLE"
 130 ><I
 131 >type</I
 132 ></TT
 133 ></TT
 134 >] [<TT
 135 CLASS="OPTION"
 136 >-v <TT
 137 CLASS="REPLACEABLE"
 138 ><I
 139 >level</I
 140 ></TT
 141 ></TT
 142 >] {name}</P
 143 ></DIV
 144 ><DIV
 145 CLASS="REFSECT1"
 146 ><A
 147 NAME="AEN48"
 148 ></A
 149 ><H2
 150 >DESCRIPTION</H2
 151 ><P
 152 >        <B
 153 CLASS="COMMAND"
 154 >dnssec-keygen</B
 155 > generates keys for DNSSEC
 156         (Secure DNS), as defined in RFC 2535.  It can also generate
 157         keys for use with TSIG (Transaction Signatures), as
 158         defined in RFC 2845.
 159     </P
 160 ></DIV
 161 ><DIV
 162 CLASS="REFSECT1"
 163 ><A
 164 NAME="AEN52"
 165 ></A
 166 ><H2
 167 >OPTIONS</H2
 168 ><P
 169 ></P
 170 ><DIV
 171 CLASS="VARIABLELIST"
 172 ><DL
 173 ><DT
 174 >-a <TT
 175 CLASS="REPLACEABLE"
 176 ><I
 177 >algorithm</I
 178 ></TT
 179 ></DT
 180 ><DD
 181 ><P
 182 >             Selects the cryptographic algorithm.  The value of
 183               <TT
 184 CLASS="OPTION"
 185 >algorithm</TT
 186 > must be one of RSAMD5 or RSA,
 187               DSA, DH (Diffie Hellman), or HMAC-MD5.  These values
 188               are case insensitive.
 189           </P
 190 ><P
 191 >             Note that for DNSSEC, DSA is a mandatory to implement algorithm,
 192               and RSA is recommended.  For TSIG, HMAC-MD5 is mandatory.
 193           </P
 194 ></DD
 195 ><DT
 196 >-b <TT
 197 CLASS="REPLACEABLE"
 198 ><I
 199 >keysize</I
 200 ></TT
 201 ></DT
 202 ><DD
 203 ><P
 204 >              Specifies the number of bits in the key.  The choice of key
 205                size depends on the algorithm used.  RSA keys must be between
 206                512 and 2048 bits.  Diffie Hellman keys must be between
 207                128 and 4096 bits.  DSA keys must be between 512 and 1024
 208                bits and an exact multiple of 64.  HMAC-MD5 keys must be
 209                between 1 and 512 bits.
 210           </P
 211 ></DD
 212 ><DT
 213 >-n <TT
 214 CLASS="REPLACEABLE"
 215 ><I
 216 >nametype</I
 217 ></TT
 218 ></DT
 219 ><DD
 220 ><P
 221 >              Specifies the owner type of the key.  The value of
 222                <TT
 223 CLASS="OPTION"
 224 >nametype</TT
 225 > must either be ZONE (for a DNSSEC
 226                zone key), HOST or ENTITY (for a key associated with a host),
 227                or USER (for a key associated with a user).  These values are
 228                case insensitive.
 229           </P
 230 ></DD
 231 ><DT
 232 >-c <TT
 233 CLASS="REPLACEABLE"
 234 ><I
 235 >class</I
 236 ></TT
 237 ></DT
 238 ><DD
 239 ><P
 240 >              Indicates that the DNS record containing the key should have
 241                the specified class.  If not specified, class IN is used.
 242           </P
 243 ></DD
 244 ><DT
 245 >-e</DT
 246 ><DD
 247 ><P
 248 >              If generating an RSA key, use a large exponent.
 249           </P
 250 ></DD
 251 ><DT
 252 >-g <TT
 253 CLASS="REPLACEABLE"
 254 ><I
 255 >generator</I
 256 ></TT
 257 ></DT
 258 ><DD
 259 ><P
 260 >              If generating a Diffie Hellman key, use this generator.
 261                Allowed values are 2 and 5.  If no generator
 262                is specified, a known prime from RFC 2539 will be used
 263                if possible; otherwise the default is 2.
 264           </P
 265 ></DD
 266 ><DT
 267 >-h</DT
 268 ><DD
 269 ><P
 270 >              Prints a short summary of the options and arguments to
 271                <B
 272 CLASS="COMMAND"
 273 >dnssec-keygen</B
 274 >.
 275           </P
 276 ></DD
 277 ><DT
 278 >-p <TT
 279 CLASS="REPLACEABLE"
 280 ><I
 281 >protocol</I
 282 ></TT
 283 ></DT
 284 ><DD
 285 ><P
 286 >              Sets the protocol value for the generated key.  The protocol
 287                is a number between 0 and 255.  The default is 2 (email) for
 288                keys of type USER and 3 (DNSSEC) for all other key types.
 289                Other possible values for this argument are listed in
 290                RFC 2535 and its successors.
 291           </P
 292 ></DD
 293 ><DT
 294 >-r <TT
 295 CLASS="REPLACEABLE"
 296 ><I
 297 >randomdev</I
 298 ></TT
 299 ></DT
 300 ><DD
 301 ><P
 302 >              Specifies the source of randomness.  If the operating
 303                system does not provide a <TT
 304 CLASS="FILENAME"
 305 >/dev/random</TT
 306 >
 307                or equivalent device, the default source of randomness
 308                is keyboard input.  <TT
 309 CLASS="FILENAME"
 310 >randomdev</TT
 311 > specifies
 312                the name of a character device or file containing random
 313                data to be used instead of the default.  The special value
 314                <TT
 315 CLASS="FILENAME"
 316 >keyboard</TT
 317 > indicates that keyboard
 318                input should be used.
 319           </P
 320 ></DD
 321 ><DT
 322 >-s <TT
 323 CLASS="REPLACEABLE"
 324 ><I
 325 >strength</I
 326 ></TT
 327 ></DT
 328 ><DD
 329 ><P
 330 >              Specifies the strength value of the key.  The strength is
 331                a number between 0 and 15, and currently has no defined
 332                purpose in DNSSEC.
 333           </P
 334 ></DD
 335 ><DT
 336 >-t <TT
 337 CLASS="REPLACEABLE"
 338 ><I
 339 >type</I
 340 ></TT
 341 ></DT
 342 ><DD
 343 ><P
 344 >              Indicates the use of the key.  <TT
 345 CLASS="OPTION"
 346 >type</TT
 347 > must be
 348                one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
 349                is AUTHCONF.  AUTH refers to the ability to authenticate
 350                data, and CONF the ability to encrypt data.
 351           </P
 352 ></DD
 353 ><DT
 354 >-v <TT
 355 CLASS="REPLACEABLE"
 356 ><I
 357 >level</I
 358 ></TT
 359 ></DT
 360 ><DD
 361 ><P
 362 >              Sets the debugging level.
 363           </P
 364 ></DD
 365 ></DL
 366 ></DIV
 367 ></DIV
 368 ><DIV
 369 CLASS="REFSECT1"
 370 ><A
 371 NAME="AEN121"
 372 ></A
 373 ><H2
 374 >GENERATED KEYS</H2
 375 ><P
 376 >        When <B
 377 CLASS="COMMAND"
 378 >dnssec-keygen</B
 379 > completes successfully,
 380         it prints a string of the form <TT
 381 CLASS="FILENAME"
 382 >Knnnn.+aaa+iiiii</TT
 383 >
 384         to the standard output.  This is an identification string for
 385         the key it has generated.  These strings can be used as arguments
 386         to <B
 387 CLASS="COMMAND"
 388 >dnssec-makekeyset</B
 389 >.
 390     </P
 391 ><P
 392 ></P
 393 ><UL
 394 ><LI
 395 ><P
 396 >          <TT
 397 CLASS="FILENAME"
 398 >nnnn</TT
 399 > is the key name.
 400         </P
 401 ></LI
 402 ><LI
 403 ><P
 404 >          <TT
 405 CLASS="FILENAME"
 406 >aaa</TT
 407 > is the numeric representation of the
 408           algorithm.
 409         </P
 410 ></LI
 411 ><LI
 412 ><P
 413 >          <TT
 414 CLASS="FILENAME"
 415 >iiiii</TT
 416 > is the key identifier (or footprint).
 417         </P
 418 ></LI
 419 ></UL
 420 ><P
 421 >        <B
 422 CLASS="COMMAND"
 423 >dnssec-keygen</B
 424 > creates two file, with names based
 425         on the printed string.  <TT
 426 CLASS="FILENAME"
 427 >Knnnn.+aaa+iiiii.key</TT
 428 >
 429         contains the public key, and
 430         <TT
 431 CLASS="FILENAME"
 432 >Knnnn.+aaa+iiiii.private</TT
 433 > contains the private
 434         key.
 435     </P
 436 ><P
 437 >        The <TT
 438 CLASS="FILENAME"
 439 >.key</TT
 440 > file contains a DNS KEY record that
 441         can be inserted into a zone file (directly or with a $INCLUDE
 442         statement).
 443     </P
 444 ><P
 445 >        The <TT
 446 CLASS="FILENAME"
 447 >.private</TT
 448 > file contains algorithm specific
 449         fields.  For obvious security reasons, this file does not have
 450         general read permission.
 451     </P
 452 ><P
 453 >        Both <TT
 454 CLASS="FILENAME"
 455 >.key</TT
 456 > and <TT
 457 CLASS="FILENAME"
 458 >.private</TT
 459 >
 460         files are generated for symmetric encryption algorithm such as
 461         HMAC-MD5, even though the public and private key are equivalent.
 462     </P
 463 ></DIV
 464 ><DIV
 465 CLASS="REFSECT1"
 466 ><A
 467 NAME="AEN148"
 468 ></A
 469 ><H2
 470 >EXAMPLE</H2
 471 ><P
 472 >        To generate a 768-bit DSA key for the domain
 473         <TT
 474 CLASS="USERINPUT"
 475 ><B
 476 >example.com</B
 477 ></TT
 478 >, the following command would be
 479         issued:
 480     </P
 481 ><P
 482 >        <TT
 483 CLASS="USERINPUT"
 484 ><B
 485 >dnssec-keygen -a DSA -b 768 -n ZONE example.com</B
 486 ></TT
 487 >
 488     </P
 489 ><P
 490 >        The command would print a string of the form:
 491     </P
 492 ><P
 493 >        <TT
 494 CLASS="USERINPUT"
 495 ><B
 496 >Kexample.com.+003+26160</B
 497 ></TT
 498 >
 499     </P
 500 ><P
 501 >        In this example, <B
 502 CLASS="COMMAND"
 503 >dnssec-keygen</B
 504 > creates
 505         the files <TT
 506 CLASS="FILENAME"
 507 >Kexample.com.+003+26160.key</TT
 508 > and
 509         <TT
 510 CLASS="FILENAME"
 511 >Kexample.com.+003+26160.private</TT
 512 >
 513     </P
 514 ></DIV
 515 ><DIV
 516 CLASS="REFSECT1"
 517 ><A
 518 NAME="AEN161"
 519 ></A
 520 ><H2
 521 >SEE ALSO</H2
 522 ><P
 523 >      <SPAN
 524 CLASS="CITEREFENTRY"
 525 ><SPAN
 526 CLASS="REFENTRYTITLE"
 527 >dnssec-makekeyset</SPAN
 528 >(8)</SPAN
 529 >,
 530       <SPAN
 531 CLASS="CITEREFENTRY"
 532 ><SPAN
 533 CLASS="REFENTRYTITLE"
 534 >dnssec-signkey</SPAN
 535 >(8)</SPAN
 536 >,
 537       <SPAN
 538 CLASS="CITEREFENTRY"
 539 ><SPAN
 540 CLASS="REFENTRYTITLE"
 541 >dnssec-signzone</SPAN
 542 >(8)</SPAN
 543 >,
 544       <I
 545 CLASS="CITETITLE"
 546 >BIND 9 Administrator Reference Manual</I
 547 >,
 548       <I
 549 CLASS="CITETITLE"
 550 >RFC 2535</I
 551 >,
 552       <I
 553 CLASS="CITETITLE"
 554 >RFC 2845</I
 555 >,
 556       <I
 557 CLASS="CITETITLE"
 558 >RFC 2539</I
 559 >.
 560     </P
 561 ></DIV
 562 ><DIV
 563 CLASS="REFSECT1"
 564 ><A
 565 NAME="AEN177"
 566 ></A
 567 ><H2
 568 >AUTHOR</H2
 569 ><P
 570 >        Internet Systems Consortium
 571     </P
 572 ></DIV
 573 ></BODY
 574 ></HTML
 575 >