man.dnssec-keygen.html 17.4 KB
Newer Older
Mark Andrews's avatar
gregen  
Mark Andrews committed
1
<!--
Automatic Updater's avatar
regen  
Automatic Updater committed
2
 - Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
gregen  
Mark Andrews committed
3 4
 - Copyright (C) 2000-2003 Internet Software Consortium.
 - 
Automatic Updater's avatar
regen  
Automatic Updater committed
5
 - Permission to use, copy, modify, and/or distribute this software for any
Mark Andrews's avatar
gregen  
Mark Andrews committed
6 7 8 9 10 11 12 13 14 15 16
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 - 
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->
Automatic Updater's avatar
regen  
Automatic Updater committed
17
<!-- $Id: man.dnssec-keygen.html,v 1.127 2009/08/27 01:14:39 tbox Exp $ -->
Mark Andrews's avatar
gregen  
Mark Andrews committed
18 19 20 21
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>dnssec-keygen</title>
Mark Andrews's avatar
regen  
Mark Andrews committed
22
<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
Mark Andrews's avatar
gregen  
Mark Andrews committed
23 24
<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
Francis Dupont's avatar
Francis Dupont committed
25
<link rel="prev" href="man.dnssec-keyfromlabel.html" title="dnssec-keyfromlabel">
Automatic Updater's avatar
regen  
Automatic Updater committed
26
<link rel="next" href="man.dnssec-revoke.html" title="dnssec-revoke">
Mark Andrews's avatar
gregen  
Mark Andrews committed
27 28 29 30 31 32 33
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center"><span class="application">dnssec-keygen</span></th></tr>
<tr>
<td width="20%" align="left">
Automatic Updater's avatar
regen  
Automatic Updater committed
34
<a accesskey="p" href="man.dnssec-keyfromlabel.html">Prev</a> </td>
Mark Andrews's avatar
gregen  
Mark Andrews committed
35
<th width="60%" align="center">Manual pages</th>
Automatic Updater's avatar
regen  
Automatic Updater committed
36
<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-revoke.html">Next</a>
Mark Andrews's avatar
gregen  
Mark Andrews committed
37 38 39 40 41 42 43 44 45 46 47 48 49
</td>
</tr>
</table>
<hr>
</div>
<div class="refentry" lang="en">
<a name="man.dnssec-keygen"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>Name</h2>
<p><span class="application">dnssec-keygen</span> &#8212; DNSSEC key generation tool</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
Automatic Updater's avatar
regen  
Automatic Updater committed
50
<div class="cmdsynopsis"><p><code class="command">dnssec-keygen</code>  [<code class="option">-a <em class="replaceable"><code>algorithm</code></em></code>] [<code class="option">-b <em class="replaceable"><code>keysize</code></em></code>] [<code class="option">-n <em class="replaceable"><code>nametype</code></em></code>] [<code class="option">-3</code>] [<code class="option">-A <em class="replaceable"><code>date/offset</code></em></code>] [<code class="option">-C</code>] [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] [<code class="option">-D <em class="replaceable"><code>date/offset</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 <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-k</code>] [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>] [<code class="option">-p <em class="replaceable"><code>protocol</code></em></code>] [<code class="option">-R <em class="replaceable"><code>date/offset</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">-U <em class="replaceable"><code>date/offset</code></em></code>] [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] [<code class="option">-z</code>] {name}</p></div>
Mark Andrews's avatar
gregen  
Mark Andrews committed
51 52
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
53
<a name="id2607762"></a><h2>DESCRIPTION</h2>
Mark Andrews's avatar
gregen  
Mark Andrews committed
54 55
<p><span><strong class="command">dnssec-keygen</strong></span>
      generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
Mark Andrews's avatar
regen  
Mark Andrews committed
56
      and RFC 4034.  It can also generate keys for use with
Automatic Updater's avatar
regen  
Automatic Updater committed
57 58
      TSIG (Transaction Signatures) as defined in RFC 2845, or TKEY
      (Transaction Key) as defined in RFC 2930.
Mark Andrews's avatar
gregen  
Mark Andrews committed
59 60 61
    </p>
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
62
<a name="id2607776"></a><h2>OPTIONS</h2>
Mark Andrews's avatar
gregen  
Mark Andrews committed
63 64 65 66
<div class="variablelist"><dl>
<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
<dd>
<p>
Automatic Updater's avatar
regen  
Automatic Updater committed
67 68 69 70 71 72 73 74 75 76 77
            Selects the cryptographic algorithm.  For DNSSEC keys, the value
            of <code class="option">algorithm</code> must be one of RSAMD5, RSASHA1,
	    DSA, NSEC3RSASHA1, or NSEC3DSA.  For TSIG/TKEY, the value must
            be DH (Diffie Hellman), HMAC-MD5, HMAC-SHA1, HMAC-SHA224,
            HMAC-SHA256, HMAC-SHA384, or HMAC-SHA512.  These values are
            case insensitive.
          </p>
<p>
            If no algorithm is specified, then RSASHA1 will be used by
            default, unless the <code class="option">-3</code> option is specified,
            in which case NSEC3RSASHA1 will be used instead.
Mark Andrews's avatar
gregen  
Mark Andrews committed
78 79 80
          </p>
<p>
            Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
Automatic Updater's avatar
regen  
Automatic Updater committed
81 82
            algorithm, and DSA is recommended.  For TSIG, HMAC-MD5 is
	    mandatory.
Mark Andrews's avatar
gregen  
Mark Andrews committed
83 84
          </p>
<p>
Automatic Updater's avatar
regen  
Automatic Updater committed
85 86
            Note 2: DH, HMAC-MD5, and HMAC-SHA1 through HMAC-SHA512
            automatically set the -T KEY option.
Mark Andrews's avatar
gregen  
Mark Andrews committed
87 88 89
          </p>
</dd>
<dt><span class="term">-b <em class="replaceable"><code>keysize</code></em></span></dt>
Automatic Updater's avatar
regen  
Automatic Updater committed
90 91
<dd>
<p>
Mark Andrews's avatar
gregen  
Mark Andrews committed
92 93
            Specifies the number of bits in the key.  The choice of key
            size depends on the algorithm used.  RSAMD5 / RSASHA1 keys must be
Automatic Updater's avatar
regen  
Automatic Updater committed
94
            between 512 and 2048 bits.  Diffie Hellman keys must be between
Mark Andrews's avatar
gregen  
Mark Andrews committed
95 96 97
            128 and 4096 bits.  DSA keys must be between 512 and 1024
            bits and an exact multiple of 64.  HMAC-MD5 keys must be
            between 1 and 512 bits.
Automatic Updater's avatar
regen  
Automatic Updater committed
98
          </p>
Automatic Updater's avatar
regen  
Automatic Updater committed
99 100 101 102 103 104 105 106
<p>
            The key size does not need to be specified if using a default
            algorithm.  The default key size is 1024 bits for zone signing
            keys (ZSK's) and 2048 bits for key signing keys (KSK's,
            generated with <code class="option">-f KSK</code>).  However, if an
            algorithm is explicitly specified with the <code class="option">-a</code>,
            then there is no default key size, and the <code class="option">-b</code>
            must be used.
Automatic Updater's avatar
regen  
Automatic Updater committed
107 108
          </p>
</dd>
Mark Andrews's avatar
gregen  
Mark Andrews committed
109 110 111 112 113 114 115
<dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt>
<dd><p>
            Specifies the owner type of the key.  The value of
            <code class="option">nametype</code> must either be ZONE (for a DNSSEC
            zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
            a host (KEY)),
            USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
Mark Andrews's avatar
regen  
Mark Andrews committed
116 117
            These values are case insensitive.  Defaults to ZONE for DNSKEY
	    generation.
Mark Andrews's avatar
gregen  
Mark Andrews committed
118
          </p></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
<dt><span class="term">-3</span></dt>
<dd><p>
	    Use an NSEC3-capable algorithm to generate a DNSSEC key.
            If this option is used and no algorithm is explicitly
            set on the command line, NSEC3RSASHA1 will be used by
            default.
          </p></dd>
<dt><span class="term">-C</span></dt>
<dd><p>
	    Compatibility mode:  generates an old-style key, without
	    any metadata.  By default, <span><strong class="command">dnssec-keygen</strong></span>
	    will include the key's creation date in the metadata stored
	    with the private key, and other dates may be set there as well
	    (publication date, activation date, etc).  Keys that include
	    this data may be incompatible with older versions of BIND; the
	    <code class="option">-C</code> option suppresses them.
          </p></dd>
Mark Andrews's avatar
gregen  
Mark Andrews committed
136 137 138 139 140 141 142 143 144 145 146 147
<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
<dd><p>
            Indicates that the DNS record containing the key should have
            the specified class.  If not specified, class IN is used.
          </p></dd>
<dt><span class="term">-e</span></dt>
<dd><p>
            If generating an RSAMD5/RSASHA1 key, use a large exponent.
          </p></dd>
<dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt>
<dd><p>
            Set the specified flag in the flag field of the KEY/DNSKEY record.
Automatic Updater's avatar
regen  
Automatic Updater committed
148
            The only recognized flags are KSK (Key Signing Key) and REVOKE.
Mark Andrews's avatar
gregen  
Mark Andrews committed
149 150 151 152 153 154 155 156 157 158 159 160 161
          </p></dd>
<dt><span class="term">-g <em class="replaceable"><code>generator</code></em></span></dt>
<dd><p>
            If generating a Diffie Hellman key, use this generator.
            Allowed values are 2 and 5.  If no generator
            is specified, a known prime from RFC 2539 will be used
            if possible; otherwise the default is 2.
          </p></dd>
<dt><span class="term">-h</span></dt>
<dd><p>
            Prints a short summary of the options and arguments to
            <span><strong class="command">dnssec-keygen</strong></span>.
          </p></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
162 163 164 165
<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
<dd><p>
            Sets the directory in which the key files are to be written.
          </p></dd>
Mark Andrews's avatar
gregen  
Mark Andrews committed
166 167
<dt><span class="term">-k</span></dt>
<dd><p>
Automatic Updater's avatar
regen  
Automatic Updater committed
168
            Deprecated in favor of -T KEY.
Mark Andrews's avatar
gregen  
Mark Andrews committed
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
          </p></dd>
<dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt>
<dd><p>
            Sets the protocol value for the generated key.  The protocol
            is a number between 0 and 255.  The default is 3 (DNSSEC).
            Other possible values for this argument are listed in
            RFC 2535 and its successors.
          </p></dd>
<dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt>
<dd><p>
            Specifies the source of randomness.  If the operating
            system does not provide a <code class="filename">/dev/random</code>
            or equivalent device, the default source of randomness
            is keyboard input.  <code class="filename">randomdev</code>
            specifies
            the name of a character device or file containing random
            data to be used instead of the default.  The special value
            <code class="filename">keyboard</code> indicates that keyboard
            input should be used.
          </p></dd>
<dt><span class="term">-s <em class="replaceable"><code>strength</code></em></span></dt>
<dd><p>
            Specifies the strength value of the key.  The strength is
            a number between 0 and 15, and currently has no defined
            purpose in DNSSEC.
          </p></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
<dt><span class="term">-T <em class="replaceable"><code>rrtype</code></em></span></dt>
<dd>
<p>
            Specifies the resource record type to use for the key.
            <code class="option">rrtype</code> must be either DNSKEY or KEY.  The
            default is DNSKEY when using a DNSSEC algorithm, but it can be
            overridden to KEY for use with SIG(0).
          </p>
<p>
          </p>
<p>
            Using any TSIG algorithm (HMAC-* or DH) forces this option
            to KEY.
          </p>
</dd>
Mark Andrews's avatar
gregen  
Mark Andrews committed
210 211 212 213 214 215 216 217 218 219 220 221 222 223
<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt>
<dd><p>
            Indicates the use of the key.  <code class="option">type</code> must be
            one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
            is AUTHCONF.  AUTH refers to the ability to authenticate
            data, and CONF the ability to encrypt data.
          </p></dd>
<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
<dd><p>
            Sets the debugging level.
          </p></dd>
</dl></div>
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
224
<a name="id2659417"></a><h2>TIMING OPTIONS</h2>
Automatic Updater's avatar
regen  
Automatic Updater committed
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
<p>
      Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
      If the argument begins with a '+' or '-', it is interpreted as
      an offset from the present time.  If such an offset is followed
      by one of the characters 'y', 'm', 'w', 'd', or 'h', then the
      offset is computed in years, months, weeks, days, or hours,
      respectively; otherwise it is computed in seconds.
    </p>
<div class="variablelist"><dl>
<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which a key is to be published to the zone.
            After that date, the key will be included in the zone but will
            not be used to sign it.
          </p></dd>
<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which the key is to be activated.  After that
            date, the key will be included and the zone and used to sign
            it.
          </p></dd>
<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which the key is to be revoked.  After that
            date, the key will be flagged as revoked.  It will be included
            in the zone and will be used to sign it.
          </p></dd>
<dt><span class="term">-U <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which the key is to be unpublished.  After that
            date, the key will no longer be included in the zone, but it
            may remain in the key repository.
          </p></dd>
<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which the key is to be deleted.  After that
            date, the key can be removed from the key repository.
            NOTE: Keys are not currently deleted automatically; this field
            is included for informational purposes and for future
            development.
          </p></dd>
</dl></div>
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
269
<a name="id2659515"></a><h2>GENERATED KEYS</h2>
Mark Andrews's avatar
gregen  
Mark Andrews committed
270 271 272 273 274
<p>
      When <span><strong class="command">dnssec-keygen</strong></span> completes
      successfully,
      it prints a string of the form <code class="filename">Knnnn.+aaa+iiiii</code>
      to the standard output.  This is an identification string for
Mark Andrews's avatar
regen  
Mark Andrews committed
275
      the key it has generated.
Mark Andrews's avatar
gregen  
Mark Andrews committed
276 277 278 279 280 281 282 283 284 285 286 287 288
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="filename">nnnn</code> is the key name.
        </p></li>
<li><p><code class="filename">aaa</code> is the numeric representation
          of the
          algorithm.
        </p></li>
<li><p><code class="filename">iiiii</code> is the key identifier (or
          footprint).
        </p></li>
</ul></div>
<p><span><strong class="command">dnssec-keygen</strong></span> 
Mark Andrews's avatar
regen  
Mark Andrews committed
289
      creates two files, with names based
Mark Andrews's avatar
gregen  
Mark Andrews committed
290 291 292 293 294 295 296 297 298 299 300 301 302
      on the printed string.  <code class="filename">Knnnn.+aaa+iiiii.key</code>
      contains the public key, and
      <code class="filename">Knnnn.+aaa+iiiii.private</code> contains the
      private
      key.
    </p>
<p>
      The <code class="filename">.key</code> file contains a DNS KEY record
      that
      can be inserted into a zone file (directly or with a $INCLUDE
      statement).
    </p>
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
303 304
      The <code class="filename">.private</code> file contains
      algorithm-specific
Mark Andrews's avatar
gregen  
Mark Andrews committed
305 306 307 308 309
      fields.  For obvious security reasons, this file does not have
      general read permission.
    </p>
<p>
      Both <code class="filename">.key</code> and <code class="filename">.private</code>
Mark Andrews's avatar
regen  
Mark Andrews committed
310
      files are generated for symmetric encryption algorithms such as
Mark Andrews's avatar
gregen  
Mark Andrews committed
311 312 313 314
      HMAC-MD5, even though the public and private key are equivalent.
    </p>
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
315
<a name="id2659623"></a><h2>EXAMPLE</h2>
Mark Andrews's avatar
gregen  
Mark Andrews committed
316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
<p>
      To generate a 768-bit DSA key for the domain
      <strong class="userinput"><code>example.com</code></strong>, the following command would be
      issued:
    </p>
<p><strong class="userinput"><code>dnssec-keygen -a DSA -b 768 -n ZONE example.com</code></strong>
    </p>
<p>
      The command would print a string of the form:
    </p>
<p><strong class="userinput"><code>Kexample.com.+003+26160</code></strong>
    </p>
<p>
      In this example, <span><strong class="command">dnssec-keygen</strong></span> creates
      the files <code class="filename">Kexample.com.+003+26160.key</code>
      and
Mark Andrews's avatar
regen  
Mark Andrews committed
332
      <code class="filename">Kexample.com.+003+26160.private</code>.
Mark Andrews's avatar
gregen  
Mark Andrews committed
333 334 335
    </p>
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
336
<a name="id2659748"></a><h2>SEE ALSO</h2>
Mark Andrews's avatar
gregen  
Mark Andrews committed
337 338
<p><span class="citerefentry"><span class="refentrytitle">dnssec-signzone</span>(8)</span>,
      <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
Automatic Updater's avatar
regen  
Automatic Updater committed
339
      <em class="citetitle">RFC 2539</em>,
Mark Andrews's avatar
gregen  
Mark Andrews committed
340
      <em class="citetitle">RFC 2845</em>,
Automatic Updater's avatar
regen  
Automatic Updater committed
341
      <em class="citetitle">RFC 4033</em>.
Mark Andrews's avatar
gregen  
Mark Andrews committed
342 343 344
    </p>
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
345
<a name="id2659779"></a><h2>AUTHOR</h2>
Mark Andrews's avatar
gregen  
Mark Andrews committed
346 347 348 349 350 351 352 353 354
<p><span class="corpauthor">Internet Systems Consortium</span>
    </p>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
Automatic Updater's avatar
regen  
Automatic Updater committed
355
<a accesskey="p" href="man.dnssec-keyfromlabel.html">Prev</a> </td>
Mark Andrews's avatar
gregen  
Mark Andrews committed
356
<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
Automatic Updater's avatar
regen  
Automatic Updater committed
357
<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-revoke.html">Next</a>
Mark Andrews's avatar
gregen  
Mark Andrews committed
358 359 360
</td>
</tr>
<tr>
Automatic Updater's avatar
regen  
Automatic Updater committed
361 362
<td width="40%" align="left" valign="top">
<span class="application">dnssec-keyfromlabel</span> </td>
Mark Andrews's avatar
gregen  
Mark Andrews committed
363
<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
Automatic Updater's avatar
regen  
Automatic Updater committed
364
<td width="40%" align="right" valign="top"> <span class="application">dnssec-revoke</span>
Mark Andrews's avatar
regen  
Mark Andrews committed
365
</td>
Mark Andrews's avatar
gregen  
Mark Andrews committed
366 367 368 369 370
</tr>
</table>
</div>
</body>
</html>