PageRenderTime 27ms CodeModel.GetById 18ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/bind9/bin/dnssec/dnssec-keygen.docbook

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 613 lines | 568 code | 45 blank | 0 comment | 0 complexity | 5299345c394fb3cebf6b3f13222c680f MD5 | raw file
  1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  2               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
  3	       [<!ENTITY mdash "&#8212;">]>
  4<!--
  5 - Copyright (C) 2004, 2005, 2007-2010  Internet Systems Consortium, Inc. ("ISC")
  6 - Copyright (C) 2000-2003  Internet Software Consortium.
  7 -
  8 - Permission to use, copy, modify, and/or distribute this software for any
  9 - purpose with or without fee is hereby granted, provided that the above
 10 - copyright notice and this permission notice appear in all copies.
 11 -
 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 14 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 18 - PERFORMANCE OF THIS SOFTWARE.
 19-->
 20
 21<!-- $Id: dnssec-keygen.docbook,v 1.36 2010/12/23 04:07:59 marka Exp $ -->
 22<refentry id="man.dnssec-keygen">
 23  <refentryinfo>
 24    <date>June 30, 2000</date>
 25  </refentryinfo>
 26
 27  <refmeta>
 28    <refentrytitle><application>dnssec-keygen</application></refentrytitle>
 29    <manvolnum>8</manvolnum>
 30    <refmiscinfo>BIND9</refmiscinfo>
 31  </refmeta>
 32
 33  <refnamediv>
 34    <refname><application>dnssec-keygen</application></refname>
 35    <refpurpose>DNSSEC key generation tool</refpurpose>
 36  </refnamediv>
 37
 38  <docinfo>
 39    <copyright>
 40      <year>2004</year>
 41      <year>2005</year>
 42      <year>2007</year>
 43      <year>2008</year>
 44      <year>2009</year>
 45      <year>2010</year>
 46      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
 47    </copyright>
 48    <copyright>
 49      <year>2000</year>
 50      <year>2001</year>
 51      <year>2002</year>
 52      <year>2003</year>
 53      <holder>Internet Software Consortium.</holder>
 54    </copyright>
 55  </docinfo>
 56
 57  <refsynopsisdiv>
 58    <cmdsynopsis>
 59      <command>dnssec-keygen</command>
 60      <arg><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
 61      <arg ><option>-b <replaceable class="parameter">keysize</replaceable></option></arg>
 62      <arg><option>-n <replaceable class="parameter">nametype</replaceable></option></arg>
 63      <arg><option>-3</option></arg>
 64      <arg><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
 65      <arg><option>-C</option></arg>
 66      <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
 67      <arg><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
 68      <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
 69      <arg><option>-e</option></arg>
 70      <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
 71      <arg><option>-G</option></arg>
 72      <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
 73      <arg><option>-h</option></arg>
 74      <arg><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
 75      <arg><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
 76      <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
 77      <arg><option>-k</option></arg>
 78      <arg><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
 79      <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
 80      <arg><option>-q</option></arg>
 81      <arg><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
 82      <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
 83      <arg><option>-S <replaceable class="parameter">key</replaceable></option></arg>
 84      <arg><option>-s <replaceable class="parameter">strength</replaceable></option></arg>
 85      <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
 86      <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
 87      <arg><option>-z</option></arg>
 88      <arg choice="req">name</arg>
 89    </cmdsynopsis>
 90  </refsynopsisdiv>
 91
 92  <refsect1>
 93    <title>DESCRIPTION</title>
 94    <para><command>dnssec-keygen</command>
 95      generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
 96      and RFC 4034.  It can also generate keys for use with
 97      TSIG (Transaction Signatures) as defined in RFC 2845, or TKEY
 98      (Transaction Key) as defined in RFC 2930.
 99    </para>
100    <para>
101      The <option>name</option> of the key is specified on the command
102      line.  For DNSSEC keys, this must match the name of the zone for
103      which the key is being generated.
104    </para>
105  </refsect1>
106
107  <refsect1>
108    <title>OPTIONS</title>
109
110    <variablelist>
111      <varlistentry>
112        <term>-a <replaceable class="parameter">algorithm</replaceable></term>
113        <listitem>
114          <para>
115            Selects the cryptographic algorithm.  For DNSSEC keys, the value
116            of <option>algorithm</option> must be one of RSAMD5, RSASHA1,
117	    DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512 or ECCGOST.
118	    For TSIG/TKEY, the value must
119            be DH (Diffie Hellman), HMAC-MD5, HMAC-SHA1, HMAC-SHA224,
120            HMAC-SHA256, HMAC-SHA384, or HMAC-SHA512.  These values are
121            case insensitive.
122          </para>
123          <para>
124            If no algorithm is specified, then RSASHA1 will be used by
125            default, unless the <option>-3</option> option is specified,
126            in which case NSEC3RSASHA1 will be used instead.  (If
127            <option>-3</option> is used and an algorithm is specified,
128            that algorithm will be checked for compatibility with NSEC3.)
129          </para>
130          <para>
131            Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
132            algorithm, and DSA is recommended.  For TSIG, HMAC-MD5 is
133	    mandatory.
134          </para>
135          <para>
136            Note 2: DH, HMAC-MD5, and HMAC-SHA1 through HMAC-SHA512
137            automatically set the -T KEY option.
138          </para>
139        </listitem>
140      </varlistentry>
141
142      <varlistentry>
143        <term>-b <replaceable class="parameter">keysize</replaceable></term>
144        <listitem>
145          <para>
146            Specifies the number of bits in the key.  The choice of key
147            size depends on the algorithm used.  RSA keys must be
148            between 512 and 2048 bits.  Diffie Hellman keys must be between
149            128 and 4096 bits.  DSA keys must be between 512 and 1024
150            bits and an exact multiple of 64.  HMAC keys must be
151            between 1 and 512 bits.
152          </para>
153          <para>
154            The key size does not need to be specified if using a default
155            algorithm.  The default key size is 1024 bits for zone signing
156            keys (ZSK's) and 2048 bits for key signing keys (KSK's,
157            generated with <option>-f KSK</option>).  However, if an
158            algorithm is explicitly specified with the <option>-a</option>,
159            then there is no default key size, and the <option>-b</option>
160            must be used.
161          </para>
162        </listitem>
163      </varlistentry>
164
165      <varlistentry>
166        <term>-n <replaceable class="parameter">nametype</replaceable></term>
167        <listitem>
168          <para>
169            Specifies the owner type of the key.  The value of
170            <option>nametype</option> must either be ZONE (for a DNSSEC
171            zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
172            a host (KEY)),
173            USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
174            These values are case insensitive.  Defaults to ZONE for DNSKEY
175	    generation.
176          </para>
177        </listitem>
178      </varlistentry>
179
180      <varlistentry>
181        <term>-3</term>
182        <listitem>
183          <para>
184	    Use an NSEC3-capable algorithm to generate a DNSSEC key.
185            If this option is used and no algorithm is explicitly
186            set on the command line, NSEC3RSASHA1 will be used by
187            default. Note that RSASHA256, RSASHA512 and ECCGOST algorithms
188	    are NSEC3-capable.
189          </para>
190        </listitem>
191      </varlistentry>
192
193      <varlistentry>
194        <term>-C</term>
195        <listitem>
196          <para>
197	    Compatibility mode:  generates an old-style key, without
198	    any metadata.  By default, <command>dnssec-keygen</command>
199	    will include the key's creation date in the metadata stored
200	    with the private key, and other dates may be set there as well
201	    (publication date, activation date, etc).  Keys that include
202	    this data may be incompatible with older versions of BIND; the
203	    <option>-C</option> option suppresses them.
204          </para>
205        </listitem>
206      </varlistentry>
207
208      <varlistentry>
209        <term>-c <replaceable class="parameter">class</replaceable></term>
210        <listitem>
211          <para>
212            Indicates that the DNS record containing the key should have
213            the specified class.  If not specified, class IN is used.
214          </para>
215        </listitem>
216      </varlistentry>
217
218      <varlistentry>
219        <term>-E <replaceable class="parameter">engine</replaceable></term>
220        <listitem>
221          <para>
222            Uses a crypto hardware (OpenSSL engine) for random number
223            and, when supported, key generation. When compiled with PKCS#11
224            support it defaults to pkcs11; the empty name resets it to
225            no engine.
226          </para>
227        </listitem>
228      </varlistentry>
229
230      <varlistentry>
231        <term>-e</term>
232        <listitem>
233          <para>
234            If generating an RSAMD5/RSASHA1 key, use a large exponent.
235          </para>
236        </listitem>
237      </varlistentry>
238
239      <varlistentry>
240        <term>-f <replaceable class="parameter">flag</replaceable></term>
241        <listitem>
242          <para>
243            Set the specified flag in the flag field of the KEY/DNSKEY record.
244            The only recognized flags are KSK (Key Signing Key) and REVOKE.
245          </para>
246        </listitem>
247      </varlistentry>
248
249      <varlistentry>
250        <term>-G</term>
251        <listitem>
252          <para>
253            Generate a key, but do not publish it or sign with it.  This
254            option is incompatible with -P and -A.
255          </para>
256        </listitem>
257      </varlistentry>
258
259      <varlistentry>
260        <term>-g <replaceable class="parameter">generator</replaceable></term>
261        <listitem>
262          <para>
263            If generating a Diffie Hellman key, use this generator.
264            Allowed values are 2 and 5.  If no generator
265            is specified, a known prime from RFC 2539 will be used
266            if possible; otherwise the default is 2.
267          </para>
268        </listitem>
269      </varlistentry>
270
271      <varlistentry>
272        <term>-h</term>
273        <listitem>
274          <para>
275            Prints a short summary of the options and arguments to
276            <command>dnssec-keygen</command>.
277          </para>
278        </listitem>
279      </varlistentry>
280
281      <varlistentry>
282        <term>-K <replaceable class="parameter">directory</replaceable></term>
283        <listitem>
284          <para>
285            Sets the directory in which the key files are to be written.
286          </para>
287        </listitem>
288      </varlistentry>
289
290      <varlistentry>
291        <term>-k</term>
292        <listitem>
293          <para>
294            Deprecated in favor of -T KEY.
295          </para>
296        </listitem>
297      </varlistentry>
298
299      <varlistentry>
300        <term>-p <replaceable class="parameter">protocol</replaceable></term>
301        <listitem>
302          <para>
303            Sets the protocol value for the generated key.  The protocol
304            is a number between 0 and 255.  The default is 3 (DNSSEC).
305            Other possible values for this argument are listed in
306            RFC 2535 and its successors.
307          </para>
308        </listitem>
309      </varlistentry>
310
311      <varlistentry>
312        <term>-q</term>
313        <listitem>
314          <para>
315            Quiet mode: Suppresses unnecessary output, including
316            progress indication.  Without this option, when
317            <command>dnssec-keygen</command> is run interactively
318            to generate an RSA or DSA key pair, it will print a string
319            of symbols to <filename>stderr</filename> indicating the
320            progress of the key generation.  A '.' indicates that a
321            random number has been found which passed an initial
322            sieve test; '+' means a number has passed a single
323            round of the Miller-Rabin primality test; a space
324            means that the number has passed all the tests and is
325            a satisfactory key.
326          </para>
327        </listitem>
328      </varlistentry>
329
330      <varlistentry>
331        <term>-r <replaceable class="parameter">randomdev</replaceable></term>
332        <listitem>
333          <para>
334            Specifies the source of randomness.  If the operating
335            system does not provide a <filename>/dev/random</filename>
336            or equivalent device, the default source of randomness
337            is keyboard input.  <filename>randomdev</filename>
338            specifies
339            the name of a character device or file containing random
340            data to be used instead of the default.  The special value
341            <filename>keyboard</filename> indicates that keyboard
342            input should be used.
343          </para>
344        </listitem>
345      </varlistentry>
346
347      <varlistentry>
348        <term>-S <replaceable class="parameter">key</replaceable></term>
349        <listitem>
350          <para>
351            Create a new key which is an explicit successor to an
352            existing key.  The name, algorithm, size, and type of the
353            key will be set to match the existing key.  The activation
354            date of the new key will be set to the inactivation date of
355            the existing one.  The publication date will be set to the
356            activation date minus the prepublication interval, which
357            defaults to 30 days.
358          </para>
359        </listitem>
360      </varlistentry>
361
362      <varlistentry>
363        <term>-s <replaceable class="parameter">strength</replaceable></term>
364        <listitem>
365          <para>
366            Specifies the strength value of the key.  The strength is
367            a number between 0 and 15, and currently has no defined
368            purpose in DNSSEC.
369          </para>
370        </listitem>
371      </varlistentry>
372
373      <varlistentry>
374        <term>-T <replaceable class="parameter">rrtype</replaceable></term>
375        <listitem>
376          <para>
377            Specifies the resource record type to use for the key.
378            <option>rrtype</option> must be either DNSKEY or KEY.  The
379            default is DNSKEY when using a DNSSEC algorithm, but it can be
380            overridden to KEY for use with SIG(0).
381          <para>
382          </para>
383            Using any TSIG algorithm (HMAC-* or DH) forces this option
384            to KEY.
385          </para>
386        </listitem>
387      </varlistentry>
388
389      <varlistentry>
390        <term>-t <replaceable class="parameter">type</replaceable></term>
391        <listitem>
392          <para>
393            Indicates the use of the key.  <option>type</option> must be
394            one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
395            is AUTHCONF.  AUTH refers to the ability to authenticate
396            data, and CONF the ability to encrypt data.
397          </para>
398        </listitem>
399      </varlistentry>
400
401      <varlistentry>
402        <term>-v <replaceable class="parameter">level</replaceable></term>
403        <listitem>
404          <para>
405            Sets the debugging level.
406          </para>
407        </listitem>
408      </varlistentry>
409
410    </variablelist>
411  </refsect1>
412
413  <refsect1>
414    <title>TIMING OPTIONS</title>
415
416    <para>
417      Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
418      If the argument begins with a '+' or '-', it is interpreted as
419      an offset from the present time.  For convenience, if such an offset
420      is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
421      then the offset is computed in years (defined as 365 24-hour days,
422      ignoring leap years), months (defined as 30 24-hour days), weeks,
423      days, hours, or minutes, respectively.  Without a suffix, the offset
424      is computed in seconds.
425    </para>
426
427    <variablelist>
428      <varlistentry>
429        <term>-P <replaceable class="parameter">date/offset</replaceable></term>
430        <listitem>
431          <para>
432            Sets the date on which a key is to be published to the zone.
433            After that date, the key will be included in the zone but will
434            not be used to sign it.  If not set, and if the -G option has
435            not been used, the default is "now".
436          </para>
437        </listitem>
438      </varlistentry>
439
440      <varlistentry>
441        <term>-A <replaceable class="parameter">date/offset</replaceable></term>
442        <listitem>
443          <para>
444            Sets the date on which the key is to be activated.  After that
445            date, the key will be included in the zone and used to sign
446            it.  If not set, and if the -G option has not been used, the
447            default is "now".
448          </para>
449        </listitem>
450      </varlistentry>
451
452      <varlistentry>
453        <term>-R <replaceable class="parameter">date/offset</replaceable></term>
454        <listitem>
455          <para>
456            Sets the date on which the key is to be revoked.  After that
457            date, the key will be flagged as revoked.  It will be included
458            in the zone and will be used to sign it.
459          </para>
460        </listitem>
461      </varlistentry>
462
463      <varlistentry>
464        <term>-I <replaceable class="parameter">date/offset</replaceable></term>
465        <listitem>
466          <para>
467            Sets the date on which the key is to be retired.  After that
468            date, the key will still be included in the zone, but it
469            will not be used to sign it.
470          </para>
471        </listitem>
472      </varlistentry>
473
474      <varlistentry>
475        <term>-D <replaceable class="parameter">date/offset</replaceable></term>
476        <listitem>
477          <para>
478            Sets the date on which the key is to be deleted.  After that
479            date, the key will no longer be included in the zone.  (It
480            may remain in the key repository, however.)
481          </para>
482        </listitem>
483      </varlistentry>
484
485      <varlistentry>
486        <term>-i <replaceable class="parameter">interval</replaceable></term>
487        <listitem>
488          <para>
489            Sets the prepublication interval for a key.  If set, then
490            the publication and activation dates must be separated by at least
491            this much time.  If the activation date is specified but the
492            publication date isn't, then the publication date will default
493            to this much time before the activation date; conversely, if
494            the publication date is specified but activation date isn't,
495            then activation will be set to this much time after publication.
496          </para>
497          <para>
498            If the key is being created as an explicit successor to another
499            key, then the default prepublication interval is 30 days; 
500            otherwise it is zero.
501          </para>
502          <para>
503            As with date offsets, if the argument is followed by one of
504            the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
505            interval is measured in years, months, weeks, days, hours,
506            or minutes, respectively.  Without a suffix, the interval is
507            measured in seconds.
508          </para>
509        </listitem>
510      </varlistentry>
511
512    </variablelist>
513  </refsect1>
514
515
516  <refsect1>
517    <title>GENERATED KEYS</title>
518    <para>
519      When <command>dnssec-keygen</command> completes
520      successfully,
521      it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
522      to the standard output.  This is an identification string for
523      the key it has generated.
524    </para>
525    <itemizedlist>
526      <listitem>
527        <para><filename>nnnn</filename> is the key name.
528        </para>
529      </listitem>
530      <listitem>
531        <para><filename>aaa</filename> is the numeric representation
532          of the
533          algorithm.
534        </para>
535      </listitem>
536      <listitem>
537        <para><filename>iiiii</filename> is the key identifier (or
538          footprint).
539        </para>
540      </listitem>
541    </itemizedlist>
542    <para><command>dnssec-keygen</command> 
543      creates two files, with names based
544      on the printed string.  <filename>Knnnn.+aaa+iiiii.key</filename>
545      contains the public key, and
546      <filename>Knnnn.+aaa+iiiii.private</filename> contains the
547      private
548      key.
549    </para>
550    <para>
551      The <filename>.key</filename> file contains a DNS KEY record
552      that
553      can be inserted into a zone file (directly or with a $INCLUDE
554      statement).
555    </para>
556    <para>
557      The <filename>.private</filename> file contains
558      algorithm-specific
559      fields.  For obvious security reasons, this file does not have
560      general read permission.
561    </para>
562    <para>
563      Both <filename>.key</filename> and <filename>.private</filename>
564      files are generated for symmetric encryption algorithms such as
565      HMAC-MD5, even though the public and private key are equivalent.
566    </para>
567  </refsect1>
568
569  <refsect1>
570    <title>EXAMPLE</title>
571    <para>
572      To generate a 768-bit DSA key for the domain
573      <userinput>example.com</userinput>, the following command would be
574      issued:
575    </para>
576    <para><userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
577    </para>
578    <para>
579      The command would print a string of the form:
580    </para>
581    <para><userinput>Kexample.com.+003+26160</userinput>
582    </para>
583    <para>
584      In this example, <command>dnssec-keygen</command> creates
585      the files <filename>Kexample.com.+003+26160.key</filename>
586      and
587      <filename>Kexample.com.+003+26160.private</filename>.
588    </para>
589  </refsect1>
590
591  <refsect1>
592    <title>SEE ALSO</title>
593    <para><citerefentry>
594        <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
595      </citerefentry>,
596      <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
597      <citetitle>RFC 2539</citetitle>,
598      <citetitle>RFC 2845</citetitle>,
599      <citetitle>RFC 4034</citetitle>.
600    </para>
601  </refsect1>
602
603  <refsect1>
604    <title>AUTHOR</title>
605    <para><corpauthor>Internet Systems Consortium</corpauthor>
606    </para>
607  </refsect1>
608
609</refentry><!--
610 - Local variables:
611 - mode: sgml
612 - End:
613-->