dnssec-keygen.html 16.2 KB
Newer Older
1
<!--
Automatic Updater's avatar
regen  
Automatic Updater committed
2
 - Copyright (C) 2004, 2005, 2007-2009 Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
regen  
Mark Andrews committed
3
 - Copyright (C) 2000-2003 Internet Software Consortium.
Rob Austein's avatar
regen  
Rob Austein committed
4
 - 
Automatic Updater's avatar
regen  
Automatic Updater committed
5
 - Permission to use, copy, modify, and/or distribute this software for any
6 7
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
Rob Austein's avatar
regen  
Rob Austein committed
8
 - 
Mark Andrews's avatar
Mark Andrews committed
9 10
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
Rob Austein's avatar
regen  
Rob Austein committed
11
 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
Mark Andrews's avatar
Mark Andrews committed
12 13 14 15
 - 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.
16
-->
Automatic Updater's avatar
regen  
Automatic Updater committed
17
<!-- $Id: dnssec-keygen.html,v 1.38 2009/08/29 01:14:37 tbox Exp $ -->
Rob Austein's avatar
regen  
Rob Austein committed
18 19 20 21
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>dnssec-keygen</title>
Automatic Updater's avatar
regen  
Automatic Updater committed
22
<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
Rob Austein's avatar
regen  
Rob Austein committed
23 24
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
Mark Andrews's avatar
gregen  
Mark Andrews committed
25
<a name="man.dnssec-keygen"></a><div class="titlepage"></div>
Rob Austein's avatar
regen  
Rob Austein committed
26 27 28 29 30 31
<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
32
<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>
Rob Austein's avatar
regen  
Rob Austein committed
33 34
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
35
<a name="id2543541"></a><h2>DESCRIPTION</h2>
Rob Austein's avatar
regen  
Rob Austein committed
36 37
<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
38
      and RFC 4034.  It can also generate keys for use with
Automatic Updater's avatar
regen  
Automatic Updater committed
39 40
      TSIG (Transaction Signatures) as defined in RFC 2845, or TKEY
      (Transaction Key) as defined in RFC 2930.
Rob Austein's avatar
regen  
Rob Austein committed
41
    </p>
Automatic Updater's avatar
regen  
Automatic Updater committed
42 43 44 45 46
<p>
      The <code class="option">name</code> of the key is specified on the command
      line.  For DNSSEC keys, this must match the name of the zone for
      which the key is being generated.
    </p>
Rob Austein's avatar
regen  
Rob Austein committed
47 48
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
49
<a name="id2543559"></a><h2>OPTIONS</h2>
Rob Austein's avatar
regen  
Rob Austein committed
50 51 52 53
<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
54 55 56 57 58 59 60 61 62 63 64
            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.
Rob Austein's avatar
regen  
Rob Austein committed
65 66 67
          </p>
<p>
            Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
Automatic Updater's avatar
regen  
Automatic Updater committed
68 69
            algorithm, and DSA is recommended.  For TSIG, HMAC-MD5 is
	    mandatory.
Rob Austein's avatar
regen  
Rob Austein committed
70 71
          </p>
<p>
Automatic Updater's avatar
regen  
Automatic Updater committed
72 73
            Note 2: DH, HMAC-MD5, and HMAC-SHA1 through HMAC-SHA512
            automatically set the -T KEY option.
Rob Austein's avatar
regen  
Rob Austein committed
74 75 76
          </p>
</dd>
<dt><span class="term">-b <em class="replaceable"><code>keysize</code></em></span></dt>
77 78
<dd>
<p>
Rob Austein's avatar
regen  
Rob Austein committed
79 80
            Specifies the number of bits in the key.  The choice of key
            size depends on the algorithm used.  RSAMD5 / RSASHA1 keys must be
81
            between 512 and 2048 bits.  Diffie Hellman keys must be between
Rob Austein's avatar
regen  
Rob Austein committed
82 83 84
            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.
85
          </p>
Automatic Updater's avatar
regen  
Automatic Updater committed
86 87 88 89 90 91 92 93
<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.
94 95
          </p>
</dd>
Rob Austein's avatar
regen  
Rob Austein committed
96 97 98 99 100 101 102
<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
103 104
            These values are case insensitive.  Defaults to ZONE for DNSKEY
	    generation.
Rob Austein's avatar
regen  
Rob Austein committed
105
          </p></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
<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>
Rob Austein's avatar
regen  
Rob Austein committed
123 124 125 126 127 128 129 130 131 132 133 134
<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
135
            The only recognized flags are KSK (Key Signing Key) and REVOKE.
Rob Austein's avatar
regen  
Rob Austein committed
136 137 138 139 140 141 142 143 144 145 146 147 148
          </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
149 150 151 152
<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>
Rob Austein's avatar
regen  
Rob Austein committed
153 154
<dt><span class="term">-k</span></dt>
<dd><p>
Automatic Updater's avatar
regen  
Automatic Updater committed
155
            Deprecated in favor of -T KEY.
Rob Austein's avatar
regen  
Rob Austein committed
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
          </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
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196
<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>
Rob Austein's avatar
regen  
Rob Austein committed
197 198 199 200 201 202 203 204 205 206 207 208 209 210
<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
211
<a name="id2544058"></a><h2>TIMING OPTIONS</h2>
Automatic Updater's avatar
regen  
Automatic Updater committed
212 213 214 215 216 217 218 219 220 221 222 223 224 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
<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
256
<a name="id2544156"></a><h2>GENERATED KEYS</h2>
Rob Austein's avatar
regen  
Rob Austein committed
257 258 259 260 261
<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
262
      the key it has generated.
Rob Austein's avatar
regen  
Rob Austein committed
263 264 265 266 267 268
    </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
Brian Wellington's avatar
Brian Wellington committed
269
          algorithm.
Rob Austein's avatar
regen  
Rob Austein committed
270 271 272 273 274 275
        </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
276
      creates two files, with names based
Rob Austein's avatar
regen  
Rob Austein committed
277 278 279 280 281 282 283 284 285 286 287 288 289
      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
290 291
      The <code class="filename">.private</code> file contains
      algorithm-specific
Rob Austein's avatar
regen  
Rob Austein committed
292 293 294 295 296
      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
297
      files are generated for symmetric encryption algorithms such as
Rob Austein's avatar
regen  
Rob Austein committed
298 299 300 301
      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
302
<a name="id2544238"></a><h2>EXAMPLE</h2>
Rob Austein's avatar
regen  
Rob Austein committed
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318
<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
319
      <code class="filename">Kexample.com.+003+26160.private</code>.
Rob Austein's avatar
regen  
Rob Austein committed
320 321 322
    </p>
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
323
<a name="id2544282"></a><h2>SEE ALSO</h2>
Rob Austein's avatar
regen  
Rob Austein committed
324 325
<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
326
      <em class="citetitle">RFC 2539</em>,
Rob Austein's avatar
regen  
Rob Austein committed
327
      <em class="citetitle">RFC 2845</em>,
Automatic Updater's avatar
regen  
Automatic Updater committed
328
      <em class="citetitle">RFC 4033</em>.
Rob Austein's avatar
regen  
Rob Austein committed
329 330 331
    </p>
</div>
<div class="refsect1" lang="en">
Automatic Updater's avatar
regen  
Automatic Updater committed
332
<a name="id2544313"></a><h2>AUTHOR</h2>
Rob Austein's avatar
regen  
Rob Austein committed
333 334 335 336 337
<p><span class="corpauthor">Internet Systems Consortium</span>
    </p>
</div>
</div></body>
</html>