contrib/bind9/doc/arm/man.dnssec-keygen.html

   1 <!--
   2  - Copyright (C) 2004-2008 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000-2003 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 <!-- $Id: man.dnssec-keygen.html,v 1.2.2.66 2008/10/18 01:29:59 tbox Exp $ -->
  18 <html>
  19 <head>
  20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  21 <title>dnssec-keygen</title>
  22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
  23 <link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
  24 <link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
  25 <link rel="prev" href="man.host.html" title="host">
  26 <link rel="next" href="man.dnssec-signzone.html" title="dnssec-signzone">
  27 </head>
  28 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  29 <div class="navheader">
  30 <table width="100%" summary="Navigation header">
  31 <tr><th colspan="3" align="center"><span class="application">dnssec-keygen</span></th></tr>
  32 <tr>
  33 <td width="20%" align="left">
  34 <a accesskey="p" href="man.host.html">Prev</a> </td>
  35 <th width="60%" align="center">Manual pages</th>
  36 <td width="20%" align="right"> <a accesskey="n" href="man.dnssec-signzone.html">Next</a>
  37 </td>
  38 </tr>
  39 </table>
  40 <hr>
  41 </div>
  42 <div class="refentry" lang="en">
  43 <a name="man.dnssec-keygen"></a><div class="titlepage"></div>
  44 <div class="refnamediv">
  45 <h2>Name</h2>
  46 <p><span class="application">dnssec-keygen</span> &#8212; DNSSEC key generation tool</p>
  47 </div>
  48 <div class="refsynopsisdiv">
  49 <h2>Synopsis</h2>
  50 <div class="cmdsynopsis"><p><code class="command">dnssec-keygen</code>  {-a <em class="replaceable"><code>algorithm</code></em>} {-b <em class="replaceable"><code>keysize</code></em>} {-n <em class="replaceable"><code>nametype</code></em>} [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] [<code class="option">-e</code>] [<code class="option">-f <em class="replaceable"><code>flag</code></em></code>] [<code class="option">-g <em class="replaceable"><code>generator</code></em></code>] [<code class="option">-h</code>] [<code class="option">-k</code>] [<code class="option">-p <em class="replaceable"><code>protocol</code></em></code>] [<code class="option">-r <em class="replaceable"><code>randomdev</code></em></code>] [<code class="option">-s <em class="replaceable"><code>strength</code></em></code>] [<code class="option">-t <em class="replaceable"><code>type</code></em></code>] [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] {name}</p></div>
  51 </div>
  52 <div class="refsect1" lang="en">
  53 <a name="id2598403"></a><h2>DESCRIPTION</h2>
  54 <p><span><strong class="command">dnssec-keygen</strong></span>
  55       generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
  56       and RFC 4034.  It can also generate keys for use with
  57       TSIG (Transaction Signatures), as defined in RFC 2845.
  58     </p>
  59 </div>
  60 <div class="refsect1" lang="en">
  61 <a name="id2598417"></a><h2>OPTIONS</h2>
  62 <div class="variablelist"><dl>
  63 <dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
  64 <dd>
  65 <p>
  66             Selects the cryptographic algorithm.  The value of
  67             <code class="option">algorithm</code> must be one of RSAMD5 (RSA) or RSASHA1,
  68                       DSA, DH (Diffie Hellman), or HMAC-MD5.  These values
  69             are case insensitive.
  70           </p>
  71 <p>
  72             Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
  73             algorithm,
  74             and DSA is recommended.  For TSIG, HMAC-MD5 is mandatory.
  75           </p>
  76 <p>
  77             Note 2: HMAC-MD5 and DH automatically set the -k flag.
  78           </p>
  79 </dd>
  80 <dt><span class="term">-b <em class="replaceable"><code>keysize</code></em></span></dt>
  81 <dd><p>
  82             Specifies the number of bits in the key.  The choice of key
  83             size depends on the algorithm used.  RSAMD5 / RSASHA1 keys must be
  84             between
  85             512 and 2048 bits.  Diffie Hellman keys must be between
  86             128 and 4096 bits.  DSA keys must be between 512 and 1024
  87             bits and an exact multiple of 64.  HMAC-MD5 keys must be
  88             between 1 and 512 bits.
  89           </p></dd>
  90 <dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt>
  91 <dd><p>
  92             Specifies the owner type of the key.  The value of
  93             <code class="option">nametype</code> must either be ZONE (for a DNSSEC
  94             zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
  95             a host (KEY)),
  96             USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
  97             These values are
  98             case insensitive.
  99           </p></dd>
 100 <dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
 101 <dd><p>
 102             Indicates that the DNS record containing the key should have
 103             the specified class.  If not specified, class IN is used.
 104           </p></dd>
 105 <dt><span class="term">-e</span></dt>
 106 <dd><p>
 107             If generating an RSAMD5/RSASHA1 key, use a large exponent.
 108           </p></dd>
 109 <dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt>
 110 <dd><p>
 111             Set the specified flag in the flag field of the KEY/DNSKEY record.
 112                         The only recognized flag is KSK (Key Signing Key) DNSKEY.
 113           </p></dd>
 114 <dt><span class="term">-g <em class="replaceable"><code>generator</code></em></span></dt>
 115 <dd><p>
 116             If generating a Diffie Hellman key, use this generator.
 117             Allowed values are 2 and 5.  If no generator
 118             is specified, a known prime from RFC 2539 will be used
 119             if possible; otherwise the default is 2.
 120           </p></dd>
 121 <dt><span class="term">-h</span></dt>
 122 <dd><p>
 123             Prints a short summary of the options and arguments to
 124             <span><strong class="command">dnssec-keygen</strong></span>.
 125           </p></dd>
 126 <dt><span class="term">-k</span></dt>
 127 <dd><p>
 128             Generate KEY records rather than DNSKEY records.
 129           </p></dd>
 130 <dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt>
 131 <dd><p>
 132             Sets the protocol value for the generated key.  The protocol
 133             is a number between 0 and 255.  The default is 3 (DNSSEC).
 134             Other possible values for this argument are listed in
 135             RFC 2535 and its successors.
 136           </p></dd>
 137 <dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt>
 138 <dd><p>
 139             Specifies the source of randomness.  If the operating
 140             system does not provide a <code class="filename">/dev/random</code>
 141             or equivalent device, the default source of randomness
 142             is keyboard input.  <code class="filename">randomdev</code>
 143             specifies
 144             the name of a character device or file containing random
 145             data to be used instead of the default.  The special value
 146             <code class="filename">keyboard</code> indicates that keyboard
 147             input should be used.
 148           </p></dd>
 149 <dt><span class="term">-s <em class="replaceable"><code>strength</code></em></span></dt>
 150 <dd><p>
 151             Specifies the strength value of the key.  The strength is
 152             a number between 0 and 15, and currently has no defined
 153             purpose in DNSSEC.
 154           </p></dd>
 155 <dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt>
 156 <dd><p>
 157             Indicates the use of the key.  <code class="option">type</code> must be
 158             one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
 159             is AUTHCONF.  AUTH refers to the ability to authenticate
 160             data, and CONF the ability to encrypt data.
 161           </p></dd>
 162 <dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
 163 <dd><p>
 164             Sets the debugging level.
 165           </p></dd>
 166 </dl></div>
 167 </div>
 168 <div class="refsect1" lang="en">
 169 <a name="id2598692"></a><h2>GENERATED KEYS</h2>
 170 <p>
 171       When <span><strong class="command">dnssec-keygen</strong></span> completes
 172       successfully,
 173       it prints a string of the form <code class="filename">Knnnn.+aaa+iiiii</code>
 174       to the standard output.  This is an identification string for
 175       the key it has generated.
 176     </p>
 177 <div class="itemizedlist"><ul type="disc">
 178 <li><p><code class="filename">nnnn</code> is the key name.
 179         </p></li>
 180 <li><p><code class="filename">aaa</code> is the numeric representation
 181           of the
 182           algorithm.
 183         </p></li>
 184 <li><p><code class="filename">iiiii</code> is the key identifier (or
 185           footprint).
 186         </p></li>
 187 </ul></div>
 188 <p><span><strong class="command">dnssec-keygen</strong></span>
 189       creates two files, with names based
 190       on the printed string.  <code class="filename">Knnnn.+aaa+iiiii.key</code>
 191       contains the public key, and
 192       <code class="filename">Knnnn.+aaa+iiiii.private</code> contains the
 193       private
 194       key.
 195     </p>
 196 <p>
 197       The <code class="filename">.key</code> file contains a DNS KEY record
 198       that
 199       can be inserted into a zone file (directly or with a $INCLUDE
 200       statement).
 201     </p>
 202 <p>
 203       The <code class="filename">.private</code> file contains
 204       algorithm-specific
 205       fields.  For obvious security reasons, this file does not have
 206       general read permission.
 207     </p>
 208 <p>
 209       Both <code class="filename">.key</code> and <code class="filename">.private</code>
 210       files are generated for symmetric encryption algorithms such as
 211       HMAC-MD5, even though the public and private key are equivalent.
 212     </p>
 213 </div>
 214 <div class="refsect1" lang="en">
 215 <a name="id2600711"></a><h2>EXAMPLE</h2>
 216 <p>
 217       To generate a 768-bit DSA key for the domain
 218       <strong class="userinput"><code>example.com</code></strong>, the following command would be
 219       issued:
 220     </p>
 221 <p><strong class="userinput"><code>dnssec-keygen -a DSA -b 768 -n ZONE example.com</code></strong>
 222     </p>
 223 <p>
 224       The command would print a string of the form:
 225     </p>
 226 <p><strong class="userinput"><code>Kexample.com.+003+26160</code></strong>
 227     </p>
 228 <p>
 229       In this example, <span><strong class="command">dnssec-keygen</strong></span> creates
 230       the files <code class="filename">Kexample.com.+003+26160.key</code>
 231       and
 232       <code class="filename">Kexample.com.+003+26160.private</code>.
 233     </p>
 234 </div>
 235 <div class="refsect1" lang="en">
 236 <a name="id2601518"></a><h2>SEE ALSO</h2>
 237 <p><span class="citerefentry"><span class="refentrytitle">dnssec-signzone</span>(8)</span>,
 238       <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
 239       <em class="citetitle">RFC 2539</em>,
 240       <em class="citetitle">RFC 2845</em>,
 241       <em class="citetitle">RFC 4033</em>.
 242     </p>
 243 </div>
 244 <div class="refsect1" lang="en">
 245 <a name="id2601549"></a><h2>AUTHOR</h2>
 246 <p><span class="corpauthor">Internet Systems Consortium</span>
 247     </p>
 248 </div>
 249 </div>
 250 <div class="navfooter">
 251 <hr>
 252 <table width="100%" summary="Navigation footer">
 253 <tr>
 254 <td width="40%" align="left">
 255 <a accesskey="p" href="man.host.html">Prev</a> </td>
 256 <td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
 257 <td width="40%" align="right"> <a accesskey="n" href="man.dnssec-signzone.html">Next</a>
 258 </td>
 259 </tr>
 260 <tr>
 261 <td width="40%" align="left" valign="top">host </td>
 262 <td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
 263 <td width="40%" align="right" valign="top"> <span class="application">dnssec-signzone</span>
 264 </td>
 265 </tr>
 266 </table>
 267 </div>
 268 </body>
 269 </html>