PageRenderTime 32ms CodeModel.GetById 16ms app.highlight 11ms RepoModel.GetById 1ms app.codeStats 0ms

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

https://bitbucket.org/freebsd/freebsd-head/
HTML | 441 lines | 424 code | 0 blank | 17 comment | 0 complexity | 8e9329f049f5b03980c49d31a0407bbf MD5 | raw file
  1<!--
  2 - Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC")
  3 - Copyright (C) 2000-2003 Internet Software Consortium.
  4 - 
  5 - Permission to use, copy, modify, and/or 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$ -->
 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.dnssec-keyfromlabel.html" title="dnssec-keyfromlabel">
 26<link rel="next" href="man.dnssec-revoke.html" title="dnssec-revoke">
 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.dnssec-keyfromlabel.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-revoke.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>  [<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 <em class="replaceable"><code>engine</code></em></code>] [<code class="option">-e</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">-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">-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 <em class="replaceable"><code>level</code></em></code>] [<code class="option">-z</code>] {name}</p></div>
 51</div>
 52<div class="refsect1" lang="en">
 53<a name="id2614596"></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, or TKEY
 58      (Transaction Key) as defined in RFC 2930.
 59    </p>
 60<p>
 61      The <code class="option">name</code> of the key is specified on the command
 62      line.  For DNSSEC keys, this must match the name of the zone for
 63      which the key is being generated.
 64    </p>
 65</div>
 66<div class="refsect1" lang="en">
 67<a name="id2614684"></a><h2>OPTIONS</h2>
 68<div class="variablelist"><dl>
 69<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
 70<dd>
 71<p>
 72            Selects the cryptographic algorithm.  For DNSSEC keys, the value
 73            of <code class="option">algorithm</code> must be one of RSAMD5, RSASHA1,
 74	    DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512 or ECCGOST.
 75	    For TSIG/TKEY, the value must
 76            be DH (Diffie Hellman), HMAC-MD5, HMAC-SHA1, HMAC-SHA224,
 77            HMAC-SHA256, HMAC-SHA384, or HMAC-SHA512.  These values are
 78            case insensitive.
 79          </p>
 80<p>
 81            If no algorithm is specified, then RSASHA1 will be used by
 82            default, unless the <code class="option">-3</code> option is specified,
 83            in which case NSEC3RSASHA1 will be used instead.  (If
 84            <code class="option">-3</code> is used and an algorithm is specified,
 85            that algorithm will be checked for compatibility with NSEC3.)
 86          </p>
 87<p>
 88            Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
 89            algorithm, and DSA is recommended.  For TSIG, HMAC-MD5 is
 90	    mandatory.
 91          </p>
 92<p>
 93            Note 2: DH, HMAC-MD5, and HMAC-SHA1 through HMAC-SHA512
 94            automatically set the -T KEY option.
 95          </p>
 96</dd>
 97<dt><span class="term">-b <em class="replaceable"><code>keysize</code></em></span></dt>
 98<dd>
 99<p>
100            Specifies the number of bits in the key.  The choice of key
101            size depends on the algorithm used.  RSA keys must be
102            between 512 and 2048 bits.  Diffie Hellman keys must be between
103            128 and 4096 bits.  DSA keys must be between 512 and 1024
104            bits and an exact multiple of 64.  HMAC keys must be
105            between 1 and 512 bits.
106          </p>
107<p>
108            The key size does not need to be specified if using a default
109            algorithm.  The default key size is 1024 bits for zone signing
110            keys (ZSK's) and 2048 bits for key signing keys (KSK's,
111            generated with <code class="option">-f KSK</code>).  However, if an
112            algorithm is explicitly specified with the <code class="option">-a</code>,
113            then there is no default key size, and the <code class="option">-b</code>
114            must be used.
115          </p>
116</dd>
117<dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt>
118<dd><p>
119            Specifies the owner type of the key.  The value of
120            <code class="option">nametype</code> must either be ZONE (for a DNSSEC
121            zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
122            a host (KEY)),
123            USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
124            These values are case insensitive.  Defaults to ZONE for DNSKEY
125	    generation.
126          </p></dd>
127<dt><span class="term">-3</span></dt>
128<dd><p>
129	    Use an NSEC3-capable algorithm to generate a DNSSEC key.
130            If this option is used and no algorithm is explicitly
131            set on the command line, NSEC3RSASHA1 will be used by
132            default. Note that RSASHA256, RSASHA512 and ECCGOST algorithms
133	    are NSEC3-capable.
134          </p></dd>
135<dt><span class="term">-C</span></dt>
136<dd><p>
137	    Compatibility mode:  generates an old-style key, without
138	    any metadata.  By default, <span><strong class="command">dnssec-keygen</strong></span>
139	    will include the key's creation date in the metadata stored
140	    with the private key, and other dates may be set there as well
141	    (publication date, activation date, etc).  Keys that include
142	    this data may be incompatible with older versions of BIND; the
143	    <code class="option">-C</code> option suppresses them.
144          </p></dd>
145<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
146<dd><p>
147            Indicates that the DNS record containing the key should have
148            the specified class.  If not specified, class IN is used.
149          </p></dd>
150<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt>
151<dd><p>
152            Uses a crypto hardware (OpenSSL engine) for random number
153            and, when supported, key generation. When compiled with PKCS#11
154            support it defaults to pkcs11; the empty name resets it to
155            no engine.
156          </p></dd>
157<dt><span class="term">-e</span></dt>
158<dd><p>
159            If generating an RSAMD5/RSASHA1 key, use a large exponent.
160          </p></dd>
161<dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt>
162<dd><p>
163            Set the specified flag in the flag field of the KEY/DNSKEY record.
164            The only recognized flags are KSK (Key Signing Key) and REVOKE.
165          </p></dd>
166<dt><span class="term">-G</span></dt>
167<dd><p>
168            Generate a key, but do not publish it or sign with it.  This
169            option is incompatible with -P and -A.
170          </p></dd>
171<dt><span class="term">-g <em class="replaceable"><code>generator</code></em></span></dt>
172<dd><p>
173            If generating a Diffie Hellman key, use this generator.
174            Allowed values are 2 and 5.  If no generator
175            is specified, a known prime from RFC 2539 will be used
176            if possible; otherwise the default is 2.
177          </p></dd>
178<dt><span class="term">-h</span></dt>
179<dd><p>
180            Prints a short summary of the options and arguments to
181            <span><strong class="command">dnssec-keygen</strong></span>.
182          </p></dd>
183<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
184<dd><p>
185            Sets the directory in which the key files are to be written.
186          </p></dd>
187<dt><span class="term">-k</span></dt>
188<dd><p>
189            Deprecated in favor of -T KEY.
190          </p></dd>
191<dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt>
192<dd><p>
193            Sets the protocol value for the generated key.  The protocol
194            is a number between 0 and 255.  The default is 3 (DNSSEC).
195            Other possible values for this argument are listed in
196            RFC 2535 and its successors.
197          </p></dd>
198<dt><span class="term">-q</span></dt>
199<dd><p>
200            Quiet mode: Suppresses unnecessary output, including
201            progress indication.  Without this option, when
202            <span><strong class="command">dnssec-keygen</strong></span> is run interactively
203            to generate an RSA or DSA key pair, it will print a string
204            of symbols to <code class="filename">stderr</code> indicating the
205            progress of the key generation.  A '.' indicates that a
206            random number has been found which passed an initial
207            sieve test; '+' means a number has passed a single
208            round of the Miller-Rabin primality test; a space
209            means that the number has passed all the tests and is
210            a satisfactory key.
211          </p></dd>
212<dt><span class="term">-r <em class="replaceable"><code>randomdev</code></em></span></dt>
213<dd><p>
214            Specifies the source of randomness.  If the operating
215            system does not provide a <code class="filename">/dev/random</code>
216            or equivalent device, the default source of randomness
217            is keyboard input.  <code class="filename">randomdev</code>
218            specifies
219            the name of a character device or file containing random
220            data to be used instead of the default.  The special value
221            <code class="filename">keyboard</code> indicates that keyboard
222            input should be used.
223          </p></dd>
224<dt><span class="term">-S <em class="replaceable"><code>key</code></em></span></dt>
225<dd><p>
226            Create a new key which is an explicit successor to an
227            existing key.  The name, algorithm, size, and type of the
228            key will be set to match the existing key.  The activation
229            date of the new key will be set to the inactivation date of
230            the existing one.  The publication date will be set to the
231            activation date minus the prepublication interval, which
232            defaults to 30 days.
233          </p></dd>
234<dt><span class="term">-s <em class="replaceable"><code>strength</code></em></span></dt>
235<dd><p>
236            Specifies the strength value of the key.  The strength is
237            a number between 0 and 15, and currently has no defined
238            purpose in DNSSEC.
239          </p></dd>
240<dt><span class="term">-T <em class="replaceable"><code>rrtype</code></em></span></dt>
241<dd>
242<p>
243            Specifies the resource record type to use for the key.
244            <code class="option">rrtype</code> must be either DNSKEY or KEY.  The
245            default is DNSKEY when using a DNSSEC algorithm, but it can be
246            overridden to KEY for use with SIG(0).
247          </p>
248<p>
249          </p>
250<p>
251            Using any TSIG algorithm (HMAC-* or DH) forces this option
252            to KEY.
253          </p>
254</dd>
255<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt>
256<dd><p>
257            Indicates the use of the key.  <code class="option">type</code> must be
258            one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
259            is AUTHCONF.  AUTH refers to the ability to authenticate
260            data, and CONF the ability to encrypt data.
261          </p></dd>
262<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
263<dd><p>
264            Sets the debugging level.
265          </p></dd>
266</dl></div>
267</div>
268<div class="refsect1" lang="en">
269<a name="id2668243"></a><h2>TIMING OPTIONS</h2>
270<p>
271      Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
272      If the argument begins with a '+' or '-', it is interpreted as
273      an offset from the present time.  For convenience, if such an offset
274      is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
275      then the offset is computed in years (defined as 365 24-hour days,
276      ignoring leap years), months (defined as 30 24-hour days), weeks,
277      days, hours, or minutes, respectively.  Without a suffix, the offset
278      is computed in seconds.
279    </p>
280<div class="variablelist"><dl>
281<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt>
282<dd><p>
283            Sets the date on which a key is to be published to the zone.
284            After that date, the key will be included in the zone but will
285            not be used to sign it.  If not set, and if the -G option has
286            not been used, the default is "now".
287          </p></dd>
288<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt>
289<dd><p>
290            Sets the date on which the key is to be activated.  After that
291            date, the key will be included in the zone and used to sign
292            it.  If not set, and if the -G option has not been used, the
293            default is "now".
294          </p></dd>
295<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt>
296<dd><p>
297            Sets the date on which the key is to be revoked.  After that
298            date, the key will be flagged as revoked.  It will be included
299            in the zone and will be used to sign it.
300          </p></dd>
301<dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt>
302<dd><p>
303            Sets the date on which the key is to be retired.  After that
304            date, the key will still be included in the zone, but it
305            will not be used to sign it.
306          </p></dd>
307<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt>
308<dd><p>
309            Sets the date on which the key is to be deleted.  After that
310            date, the key will no longer be included in the zone.  (It
311            may remain in the key repository, however.)
312          </p></dd>
313<dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt>
314<dd>
315<p>
316            Sets the prepublication interval for a key.  If set, then
317            the publication and activation dates must be separated by at least
318            this much time.  If the activation date is specified but the
319            publication date isn't, then the publication date will default
320            to this much time before the activation date; conversely, if
321            the publication date is specified but activation date isn't,
322            then activation will be set to this much time after publication.
323          </p>
324<p>
325            If the key is being created as an explicit successor to another
326            key, then the default prepublication interval is 30 days; 
327            otherwise it is zero.
328          </p>
329<p>
330            As with date offsets, if the argument is followed by one of
331            the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
332            interval is measured in years, months, weeks, days, hours,
333            or minutes, respectively.  Without a suffix, the interval is
334            measured in seconds.
335          </p>
336</dd>
337</dl></div>
338</div>
339<div class="refsect1" lang="en">
340<a name="id2668501"></a><h2>GENERATED KEYS</h2>
341<p>
342      When <span><strong class="command">dnssec-keygen</strong></span> completes
343      successfully,
344      it prints a string of the form <code class="filename">Knnnn.+aaa+iiiii</code>
345      to the standard output.  This is an identification string for
346      the key it has generated.
347    </p>
348<div class="itemizedlist"><ul type="disc">
349<li><p><code class="filename">nnnn</code> is the key name.
350        </p></li>
351<li><p><code class="filename">aaa</code> is the numeric representation
352          of the
353          algorithm.
354        </p></li>
355<li><p><code class="filename">iiiii</code> is the key identifier (or
356          footprint).
357        </p></li>
358</ul></div>
359<p><span><strong class="command">dnssec-keygen</strong></span> 
360      creates two files, with names based
361      on the printed string.  <code class="filename">Knnnn.+aaa+iiiii.key</code>
362      contains the public key, and
363      <code class="filename">Knnnn.+aaa+iiiii.private</code> contains the
364      private
365      key.
366    </p>
367<p>
368      The <code class="filename">.key</code> file contains a DNS KEY record
369      that
370      can be inserted into a zone file (directly or with a $INCLUDE
371      statement).
372    </p>
373<p>
374      The <code class="filename">.private</code> file contains
375      algorithm-specific
376      fields.  For obvious security reasons, this file does not have
377      general read permission.
378    </p>
379<p>
380      Both <code class="filename">.key</code> and <code class="filename">.private</code>
381      files are generated for symmetric encryption algorithms such as
382      HMAC-MD5, even though the public and private key are equivalent.
383    </p>
384</div>
385<div class="refsect1" lang="en">
386<a name="id2668609"></a><h2>EXAMPLE</h2>
387<p>
388      To generate a 768-bit DSA key for the domain
389      <strong class="userinput"><code>example.com</code></strong>, the following command would be
390      issued:
391    </p>
392<p><strong class="userinput"><code>dnssec-keygen -a DSA -b 768 -n ZONE example.com</code></strong>
393    </p>
394<p>
395      The command would print a string of the form:
396    </p>
397<p><strong class="userinput"><code>Kexample.com.+003+26160</code></strong>
398    </p>
399<p>
400      In this example, <span><strong class="command">dnssec-keygen</strong></span> creates
401      the files <code class="filename">Kexample.com.+003+26160.key</code>
402      and
403      <code class="filename">Kexample.com.+003+26160.private</code>.
404    </p>
405</div>
406<div class="refsect1" lang="en">
407<a name="id2668665"></a><h2>SEE ALSO</h2>
408<p><span class="citerefentry"><span class="refentrytitle">dnssec-signzone</span>(8)</span>,
409      <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
410      <em class="citetitle">RFC 2539</em>,
411      <em class="citetitle">RFC 2845</em>,
412      <em class="citetitle">RFC 4034</em>.
413    </p>
414</div>
415<div class="refsect1" lang="en">
416<a name="id2668696"></a><h2>AUTHOR</h2>
417<p><span class="corpauthor">Internet Systems Consortium</span>
418    </p>
419</div>
420</div>
421<div class="navfooter">
422<hr>
423<table width="100%" summary="Navigation footer">
424<tr>
425<td width="40%" align="left">
426<a accesskey="p" href="man.dnssec-keyfromlabel.html">Prev</a> </td>
427<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
428<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-revoke.html">Next</a>
429</td>
430</tr>
431<tr>
432<td width="40%" align="left" valign="top">
433<span class="application">dnssec-keyfromlabel</span> </td>
434<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
435<td width="40%" align="right" valign="top"> <span class="application">dnssec-revoke</span>
436</td>
437</tr>
438</table>
439</div>
440</body>
441</html>