dnssec-keygen.html 21.5 KB
Newer Older
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2
<!--
Tinderbox User's avatar
Tinderbox User committed
3
 - Copyright (C) 2000-2005, 2007-2012, 2014-2018 Internet Systems Consortium, Inc. ("ISC")
Rob Austein's avatar
regen  
Rob Austein committed
4
 - 
Tinderbox User's avatar
Tinderbox User committed
5 6 7
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
8
-->
9
<html lang="en">
Rob Austein's avatar
regen  
Rob Austein committed
10 11 12
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>dnssec-keygen</title>
Tinderbox User's avatar
Tinderbox User committed
13
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
Rob Austein's avatar
regen  
Rob Austein committed
14
</head>
Tinderbox User's avatar
Tinderbox User committed
15
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
Mark Andrews's avatar
gregen  
Mark Andrews committed
16
<a name="man.dnssec-keygen"></a><div class="titlepage"></div>
Tinderbox User's avatar
Tinderbox User committed
17 18 19 20 21 22
  
  

  

  <div class="refnamediv">
Rob Austein's avatar
regen  
Rob Austein committed
23
<h2>Name</h2>
Tinderbox User's avatar
Tinderbox User committed
24 25 26 27
<p>
    <span class="application">dnssec-keygen</span>
     &#8212; DNSSEC key generation tool
  </p>
Rob Austein's avatar
regen  
Rob Austein committed
28
</div>
Tinderbox User's avatar
Tinderbox User committed
29 30 31 32

  

  <div class="refsynopsisdiv">
Rob Austein's avatar
regen  
Rob Austein committed
33
<h2>Synopsis</h2>
Tinderbox User's avatar
Tinderbox User committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
    <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">-D sync <em class="replaceable"><code>date/offset</code></em></code>]
       [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>]
       [<code class="option">-f <em class="replaceable"><code>flag</code></em></code>]
       [<code class="option">-G</code>]
       [<code class="option">-g <em class="replaceable"><code>generator</code></em></code>]
       [<code class="option">-h</code>]
       [<code class="option">-I <em class="replaceable"><code>date/offset</code></em></code>]
       [<code class="option">-i <em class="replaceable"><code>interval</code></em></code>]
       [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>]
       [<code class="option">-k</code>]
       [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>]
       [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>]
       [<code class="option">-P sync <em class="replaceable"><code>date/offset</code></em></code>]
       [<code class="option">-p <em class="replaceable"><code>protocol</code></em></code>]
       [<code class="option">-q</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>key</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</code>]
       [<code class="option">-v <em class="replaceable"><code>level</code></em></code>]
       [<code class="option">-z</code>]
       {name}
    </p></div>
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
72
<a name="id-1.7"></a><h2>DESCRIPTION</h2>
Tinderbox User's avatar
Tinderbox User committed
73 74

    <p><span class="command"><strong>dnssec-keygen</strong></span>
Rob Austein's avatar
regen  
Rob Austein committed
75
      generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
Mark Andrews's avatar
regen  
Mark Andrews committed
76
      and RFC 4034.  It can also generate keys for use with
Automatic Updater's avatar
regen  
Automatic Updater committed
77 78
      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
79
    </p>
Tinderbox User's avatar
Tinderbox User committed
80
    <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
81 82 83 84
      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>
Tinderbox User's avatar
Tinderbox User committed
85 86 87 88 89 90 91
    <p>
      The <span class="command"><strong>dnssec-keymgr</strong></span> command acts as a wrapper
      around <span class="command"><strong>dnssec-keygen</strong></span>, generating and updating keys
      as needed to enforce defined security policies such as key rollover
      scheduling. Using <span class="command"><strong>dnssec-keymgr</strong></span> may be preferable
      to direct use of <span class="command"><strong>dnssec-keygen</strong></span>.
    </p>
Tinderbox User's avatar
Tinderbox User committed
92 93 94
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
95
<a name="id-1.8"></a><h2>OPTIONS</h2>
Tinderbox User's avatar
Tinderbox User committed
96 97 98


    <div class="variablelist"><dl class="variablelist">
Rob Austein's avatar
regen  
Rob Austein committed
99 100
<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
101
	  <p>
Tinderbox User's avatar
Tinderbox User committed
102 103
	    Selects the cryptographic algorithm.  For DNSSEC keys, the value
	    of <code class="option">algorithm</code> must be one of RSAMD5, RSASHA1,
104
	    DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512, ECCGOST,
Tinderbox User's avatar
Tinderbox User committed
105
	    ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448.  For
Tinderbox User's avatar
Tinderbox User committed
106 107 108
	    TKEY, the value must be DH (Diffie Hellman); specifying
	    his value will automatically set the <code class="option">-T KEY</code>
	    option as well.
Tinderbox User's avatar
Tinderbox User committed
109
	  </p>
Tinderbox User's avatar
Tinderbox User committed
110
	  <p>
Tinderbox User's avatar
Tinderbox User committed
111 112 113 114 115
	    These values are case insensitive. In some cases, abbreviations
	    are supported, such as ECDSA256 for ECDSAP256SHA256 and
	    ECDSA384 for ECDSAP384SHA384. If RSASHA1 or DSA is specified
	    along with the <code class="option">-3</code> option, then NSEC3RSASHA1
	    or NSEC3DSA will be used instead.
Tinderbox User's avatar
Tinderbox User committed
116
	  </p>
Tinderbox User's avatar
Tinderbox User committed
117
	  <p>
Tinderbox User's avatar
Tinderbox User committed
118 119 120 121 122 123 124 125 126
	    This parameter <span class="emphasis"><em>must</em></span> be specified except
	    when using the <code class="option">-S</code> option, which copies the
	    algorithm from the predecessor key.
	  </p>
	  <p>
	    In prior releases, HMAC algorithms could be generated for
	    use as TSIG keys, but that feature has been removed as of
	    BIND 9.13.0. Use <span class="command"><strong>tsig-keygen</strong></span> to generate
	    TSIG keys.
Tinderbox User's avatar
Tinderbox User committed
127
	  </p>
Tinderbox User's avatar
Tinderbox User committed
128
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
129
<dt><span class="term">-b <em class="replaceable"><code>keysize</code></em></span></dt>
130
<dd>
Tinderbox User's avatar
Tinderbox User committed
131
	  <p>
Tinderbox User's avatar
Tinderbox User committed
132 133
	    Specifies the number of bits in the key.  The choice of key
	    size depends on the algorithm used.  RSA keys must be
Tinderbox User's avatar
Tinderbox User committed
134
	    between 1024 and 2048 bits.  Diffie Hellman keys must be between
Tinderbox User's avatar
Tinderbox User committed
135 136 137 138 139
	    128 and 4096 bits.  DSA keys must be between 512 and 1024
	    bits and an exact multiple of 64.  HMAC keys must be
	    between 1 and 512 bits. Elliptic curve algorithms don't need
	    this parameter.
	  </p>
Tinderbox User's avatar
Tinderbox User committed
140
	  <p>
Tinderbox User's avatar
Tinderbox User committed
141 142 143 144 145
	    If the key size is not specified, some algorithms have
	    pre-defined defaults.  For example, RSA keys for use as
	    DNSSEC zone signing keys have a default size of 1024 bits;
	    RSA keys for use as key signing keys (KSKs, generated with
	    <code class="option">-f KSK</code>) default to 2048 bits.
Tinderbox User's avatar
Tinderbox User committed
146
	  </p>
Tinderbox User's avatar
Tinderbox User committed
147
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
148
<dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
149 150
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
151 152
	    Specifies the owner type of the key.  The value of
	    <code class="option">nametype</code> must either be ZONE (for a DNSSEC
Tinderbox User's avatar
Tinderbox User committed
153 154 155 156
	    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).  These values are case
	    insensitive.  Defaults to ZONE for DNSKEY generation.
Tinderbox User's avatar
Tinderbox User committed
157 158
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
159
<dt><span class="term">-3</span></dt>
Tinderbox User's avatar
Tinderbox User committed
160 161
<dd>
	  <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
162
	    Use an NSEC3-capable algorithm to generate a DNSSEC key.
Tinderbox User's avatar
Tinderbox User committed
163 164 165 166
	    If this option is used with an algorithm that has both
	    NSEC and NSEC3 versions, then the NSEC3 version will be
	    used; for example, <span class="command"><strong>dnssec-keygen -3a RSASHA1</strong></span>
	    specifies the NSEC3RSASHA1 algorithm.
Tinderbox User's avatar
Tinderbox User committed
167 168
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
169
<dt><span class="term">-C</span></dt>
Tinderbox User's avatar
Tinderbox User committed
170 171
<dd>
	  <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
172
	    Compatibility mode:  generates an old-style key, without
Tinderbox User's avatar
Tinderbox User committed
173
	    any metadata.  By default, <span class="command"><strong>dnssec-keygen</strong></span>
Automatic Updater's avatar
regen  
Automatic Updater committed
174 175 176 177 178
	    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.
Tinderbox User's avatar
Tinderbox User committed
179 180
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
181
<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
182 183
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
184 185
	    Indicates that the DNS record containing the key should have
	    the specified class.  If not specified, class IN is used.
Tinderbox User's avatar
Tinderbox User committed
186 187
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
188
<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
189
<dd>
Tinderbox User's avatar
Tinderbox User committed
190
	  <p>
Tinderbox User's avatar
Tinderbox User committed
191 192
	    Specifies the cryptographic hardware to use, when applicable.
	  </p>
Tinderbox User's avatar
Tinderbox User committed
193
	  <p>
Tinderbox User's avatar
Tinderbox User committed
194 195 196 197 198 199 200
	    When BIND is built with OpenSSL PKCS#11 support, this defaults
	    to the string "pkcs11", which identifies an OpenSSL engine
	    that can drive a cryptographic accelerator or hardware service
	    module.  When BIND is built with native PKCS#11 cryptography
	    (--enable-native-pkcs11), it defaults to the path of the PKCS#11
	    provider library specified via "--with-pkcs11".
	  </p>
Tinderbox User's avatar
Tinderbox User committed
201
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
202
<dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
203 204
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
205 206
	    Set the specified flag in the flag field of the KEY/DNSKEY record.
	    The only recognized flags are KSK (Key Signing Key) and REVOKE.
Tinderbox User's avatar
Tinderbox User committed
207 208
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
209
<dt><span class="term">-G</span></dt>
Tinderbox User's avatar
Tinderbox User committed
210 211
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
212 213
	    Generate a key, but do not publish it or sign with it.  This
	    option is incompatible with -P and -A.
Tinderbox User's avatar
Tinderbox User committed
214 215
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
216
<dt><span class="term">-g <em class="replaceable"><code>generator</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
217 218
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
219 220 221 222
	    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.
Tinderbox User's avatar
Tinderbox User committed
223 224
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
225
<dt><span class="term">-h</span></dt>
Tinderbox User's avatar
Tinderbox User committed
226 227
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
228 229
	    Prints a short summary of the options and arguments to
	    <span class="command"><strong>dnssec-keygen</strong></span>.
Tinderbox User's avatar
Tinderbox User committed
230 231
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
232
<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
233 234
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
235
	    Sets the directory in which the key files are to be written.
Tinderbox User's avatar
Tinderbox User committed
236 237
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
238
<dt><span class="term">-k</span></dt>
Tinderbox User's avatar
Tinderbox User committed
239 240
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
241
	    Deprecated in favor of -T KEY.
Tinderbox User's avatar
Tinderbox User committed
242 243
	  </p>
	</dd>
Automatic Updater's avatar
Automatic Updater committed
244
<dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
245 246
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
247 248 249 250 251 252 253 254
	    Sets the default TTL to use for this key when it is converted
	    into a DNSKEY RR.  If the key is imported into a zone,
	    this is the TTL that will be used for it, unless there was
	    already a DNSKEY RRset in place, in which case the existing TTL
	    would take precedence.  If this value is not set and there
	    is no existing DNSKEY RRset, the TTL will default to the
	    SOA TTL. Setting the default TTL to <code class="literal">0</code>
	    or <code class="literal">none</code> is the same as leaving it unset.
Tinderbox User's avatar
Tinderbox User committed
255 256
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
257
<dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
258 259
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
260 261 262 263
	    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.
Tinderbox User's avatar
Tinderbox User committed
264 265
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
266
<dt><span class="term">-q</span></dt>
Tinderbox User's avatar
Tinderbox User committed
267 268
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
269 270 271 272 273 274 275 276 277 278 279
	    Quiet mode: Suppresses unnecessary output, including
	    progress indication.  Without this option, when
	    <span class="command"><strong>dnssec-keygen</strong></span> is run interactively
	    to generate an RSA or DSA key pair, it will print a string
	    of symbols to <code class="filename">stderr</code> indicating the
	    progress of the key generation.  A '.' indicates that a
	    random number has been found which passed an initial
	    sieve test; '+' means a number has passed a single
	    round of the Miller-Rabin primality test; a space
	    means that the number has passed all the tests and is
	    a satisfactory key.
Tinderbox User's avatar
Tinderbox User committed
280 281
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
282
<dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
283 284
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
285 286 287 288 289 290 291 292 293
	    Specifies a source of randomness.  Normally, when generating
	    DNSSEC keys, this option has no effect; the random number
	    generation function provided by the cryptographic library will
	    be used.
	  </p>
	  <p>
	    If that behavior is disabled at compile time, however,
	    the specified file will be used as entropy source
	    for key generation.  <code class="filename">randomdev</code> is
Tinderbox User's avatar
Tinderbox User committed
294
	    the name of a character device or file containing random
Tinderbox User's avatar
Tinderbox User committed
295 296 297 298 299 300 301
	    data to be used.  The special value <code class="filename">keyboard</code>
	    indicates that keyboard input should be used.
	  </p>
	  <p>
	    The default is <code class="filename">/dev/random</code> if the
	    operating system provides it or an equivalent device;
	    if not, the default source of randomness is keyboard input.
Tinderbox User's avatar
Tinderbox User committed
302 303
	  </p>
	</dd>
Automatic Updater's avatar
Automatic Updater committed
304
<dt><span class="term">-S <em class="replaceable"><code>key</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
305 306
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
307 308 309 310 311 312 313
	    Create a new key which is an explicit successor to an
	    existing key.  The name, algorithm, size, and type of the
	    key will be set to match the existing key.  The activation
	    date of the new key will be set to the inactivation date of
	    the existing one.  The publication date will be set to the
	    activation date minus the prepublication interval, which
	    defaults to 30 days.
Tinderbox User's avatar
Tinderbox User committed
314 315
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
316
<dt><span class="term">-s <em class="replaceable"><code>strength</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
317 318
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
319 320 321
	    Specifies the strength value of the key.  The strength is
	    a number between 0 and 15, and currently has no defined
	    purpose in DNSSEC.
Tinderbox User's avatar
Tinderbox User committed
322 323
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
324 325
<dt><span class="term">-T <em class="replaceable"><code>rrtype</code></em></span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
326
	  <p>
Tinderbox User's avatar
Tinderbox User committed
327 328 329 330 331
	    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>
Automatic Updater's avatar
regen  
Automatic Updater committed
332
<p>
Tinderbox User's avatar
Tinderbox User committed
333
	  </p>
Automatic Updater's avatar
regen  
Automatic Updater committed
334
<p>
Tinderbox User's avatar
Tinderbox User committed
335 336
	    Specifying any TSIG algorithm (HMAC-* or DH) with
	    <code class="option">-a</code> forces this option to KEY.
Tinderbox User's avatar
Tinderbox User committed
337
	  </p>
Tinderbox User's avatar
Tinderbox User committed
338
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
339
<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
340 341
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
342 343 344 345
	    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.
Tinderbox User's avatar
Tinderbox User committed
346 347
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
348
<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
349 350
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
351
	    Sets the debugging level.
Tinderbox User's avatar
Tinderbox User committed
352 353
	  </p>
	</dd>
Tinderbox User's avatar
Tinderbox User committed
354
<dt><span class="term">-V</span></dt>
Tinderbox User's avatar
Tinderbox User committed
355 356
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
357
	    Prints version information.
Tinderbox User's avatar
Tinderbox User committed
358 359
	  </p>
	</dd>
Rob Austein's avatar
regen  
Rob Austein committed
360
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
361 362 363
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
364
<a name="id-1.9"></a><h2>TIMING OPTIONS</h2>
Tinderbox User's avatar
Tinderbox User committed
365 366 367


    <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
368 369
      Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
      If the argument begins with a '+' or '-', it is interpreted as
Automatic Updater's avatar
regen  
Automatic Updater committed
370 371 372 373 374
      an offset from the present time.  For convenience, if such an offset
      is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
      then the offset is computed in years (defined as 365 24-hour days,
      ignoring leap years), months (defined as 30 24-hour days), weeks,
      days, hours, or minutes, respectively.  Without a suffix, the offset
Tinderbox User's avatar
Tinderbox User committed
375 376
      is computed in seconds.  To explicitly prevent a date from being
      set, use 'none' or 'never'.
Automatic Updater's avatar
regen  
Automatic Updater committed
377
    </p>
Tinderbox User's avatar
Tinderbox User committed
378 379

    <div class="variablelist"><dl class="variablelist">
Automatic Updater's avatar
regen  
Automatic Updater committed
380
<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
381 382
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
383 384 385 386
	    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.  If not set, and if the -G option has
	    not been used, the default is "now".
Tinderbox User's avatar
Tinderbox User committed
387 388
	  </p>
	</dd>
Tinderbox User's avatar
Tinderbox User committed
389
<dt><span class="term">-P sync <em class="replaceable"><code>date/offset</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
390 391
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
392 393
	    Sets the date on which CDS and CDNSKEY records that match this
	    key are to be published to the zone.
Tinderbox User's avatar
Tinderbox User committed
394 395
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
396
<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
397 398
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
399 400 401 402 403 404
	    Sets the date on which the key is to be activated.  After that
	    date, the key will be included in the zone and used to sign
	    it.  If not set, and if the -G option has not been used, the
	    default is "now".  If set, if and -P is not set, then
	    the publication date will be set to the activation date
	    minus the prepublication interval.
Tinderbox User's avatar
Tinderbox User committed
405 406
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
407
<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
408 409
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
410 411 412
	    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.
Tinderbox User's avatar
Tinderbox User committed
413 414
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
415
<dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
416 417
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
418 419 420
	    Sets the date on which the key is to be retired.  After that
	    date, the key will still be included in the zone, but it
	    will not be used to sign it.
Tinderbox User's avatar
Tinderbox User committed
421 422
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
423
<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
424 425
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
426 427 428
	    Sets the date on which the key is to be deleted.  After that
	    date, the key will no longer be included in the zone.  (It
	    may remain in the key repository, however.)
Tinderbox User's avatar
Tinderbox User committed
429 430
	  </p>
	</dd>
Tinderbox User's avatar
Tinderbox User committed
431
<dt><span class="term">-D sync <em class="replaceable"><code>date/offset</code></em></span></dt>
Tinderbox User's avatar
Tinderbox User committed
432 433
<dd>
	  <p>
Tinderbox User's avatar
Tinderbox User committed
434 435
	    Sets the date on which the CDS and CDNSKEY records that match this
	    key are to be deleted.
Tinderbox User's avatar
Tinderbox User committed
436 437
	  </p>
	</dd>
Automatic Updater's avatar
Automatic Updater committed
438 439
<dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461
	  <p>
	    Sets the prepublication interval for a key.  If set, then
	    the publication and activation dates must be separated by at least
	    this much time.  If the activation date is specified but the
	    publication date isn't, then the publication date will default
	    to this much time before the activation date; conversely, if
	    the publication date is specified but activation date isn't,
	    then activation will be set to this much time after publication.
	  </p>
	  <p>
	    If the key is being created as an explicit successor to another
	    key, then the default prepublication interval is 30 days;
	    otherwise it is zero.
	  </p>
	  <p>
	    As with date offsets, if the argument is followed by one of
	    the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
	    interval is measured in years, months, weeks, days, hours,
	    or minutes, respectively.  Without a suffix, the interval is
	    measured in seconds.
	  </p>
	</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
462
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
463 464 465 466
  </div>


  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
467
<a name="id-1.10"></a><h2>GENERATED KEYS</h2>
Tinderbox User's avatar
Tinderbox User committed
468 469

    <p>
Tinderbox User's avatar
Tinderbox User committed
470
      When <span class="command"><strong>dnssec-keygen</strong></span> completes
Rob Austein's avatar
regen  
Rob Austein committed
471 472 473
      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
474
      the key it has generated.
Rob Austein's avatar
regen  
Rob Austein committed
475
    </p>
Tinderbox User's avatar
Tinderbox User committed
476 477 478 479 480 481 482
    <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
	<p><code class="filename">nnnn</code> is the key name.
	</p>
      </li>
<li class="listitem">
	<p><code class="filename">aaa</code> is the numeric representation
Tinderbox User's avatar
Tinderbox User committed
483 484
	  of the
	  algorithm.
Tinderbox User's avatar
Tinderbox User committed
485 486 487 488
	</p>
      </li>
<li class="listitem">
	<p><code class="filename">iiiii</code> is the key identifier (or
Tinderbox User's avatar
Tinderbox User committed
489
	  footprint).
Tinderbox User's avatar
Tinderbox User committed
490 491
	</p>
      </li>
Rob Austein's avatar
regen  
Rob Austein committed
492
</ul></div>
Tinderbox User's avatar
Tinderbox User committed
493
    <p><span class="command"><strong>dnssec-keygen</strong></span>
Mark Andrews's avatar
regen  
Mark Andrews committed
494
      creates two files, with names based
Rob Austein's avatar
regen  
Rob Austein committed
495 496 497 498 499 500
      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>
Tinderbox User's avatar
Tinderbox User committed
501
    <p>
Rob Austein's avatar
regen  
Rob Austein committed
502 503 504 505 506
      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>
Tinderbox User's avatar
Tinderbox User committed
507
    <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
508 509
      The <code class="filename">.private</code> file contains
      algorithm-specific
Rob Austein's avatar
regen  
Rob Austein committed
510 511 512
      fields.  For obvious security reasons, this file does not have
      general read permission.
    </p>
Tinderbox User's avatar
Tinderbox User committed
513
    <p>
Rob Austein's avatar
regen  
Rob Austein committed
514
      Both <code class="filename">.key</code> and <code class="filename">.private</code>
Tinderbox User's avatar
Tinderbox User committed
515
      files are generated for symmetric cryptography algorithms such as
Rob Austein's avatar
regen  
Rob Austein committed
516 517
      HMAC-MD5, even though the public and private key are equivalent.
    </p>
Tinderbox User's avatar
Tinderbox User committed
518 519 520
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
521
<a name="id-1.11"></a><h2>EXAMPLE</h2>
Tinderbox User's avatar
Tinderbox User committed
522 523

    <p>
Rob Austein's avatar
regen  
Rob Austein committed
524 525 526 527
      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>
Tinderbox User's avatar
Tinderbox User committed
528
    <p><strong class="userinput"><code>dnssec-keygen -a DSA -b 768 -n ZONE example.com</code></strong>
Rob Austein's avatar
regen  
Rob Austein committed
529
    </p>
Tinderbox User's avatar
Tinderbox User committed
530
    <p>
Rob Austein's avatar
regen  
Rob Austein committed
531 532
      The command would print a string of the form:
    </p>
Tinderbox User's avatar
Tinderbox User committed
533
    <p><strong class="userinput"><code>Kexample.com.+003+26160</code></strong>
Rob Austein's avatar
regen  
Rob Austein committed
534
    </p>
Tinderbox User's avatar
Tinderbox User committed
535
    <p>
Tinderbox User's avatar
Tinderbox User committed
536
      In this example, <span class="command"><strong>dnssec-keygen</strong></span> creates
Rob Austein's avatar
regen  
Rob Austein committed
537 538
      the files <code class="filename">Kexample.com.+003+26160.key</code>
      and
Mark Andrews's avatar
regen  
Mark Andrews committed
539
      <code class="filename">Kexample.com.+003+26160.private</code>.
Rob Austein's avatar
regen  
Rob Austein committed
540
    </p>
Tinderbox User's avatar
Tinderbox User committed
541 542 543
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
544
<a name="id-1.12"></a><h2>SEE ALSO</h2>
Tinderbox User's avatar
Tinderbox User committed
545 546 547 548

    <p><span class="citerefentry">
	<span class="refentrytitle">dnssec-signzone</span>(8)
      </span>,
Rob Austein's avatar
regen  
Rob Austein committed
549
      <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
Automatic Updater's avatar
regen  
Automatic Updater committed
550
      <em class="citetitle">RFC 2539</em>,
Rob Austein's avatar
regen  
Rob Austein committed
551
      <em class="citetitle">RFC 2845</em>,
Automatic Updater's avatar
regen  
Automatic Updater committed
552
      <em class="citetitle">RFC 4034</em>.
Rob Austein's avatar
regen  
Rob Austein committed
553
    </p>
Tinderbox User's avatar
Tinderbox User committed
554 555
  </div>

Rob Austein's avatar
regen  
Rob Austein committed
556 557
</div></body>
</html>