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

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <!--
   3  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   4  - Copyright (C) 2001-2003  Internet Software Consortium.
   5  -
   6  - Permission to use, copy, modify, and distribute this software for any
   7  - purpose with or without fee is hereby granted, provided that the above
   8  - copyright notice and this permission notice appear in all copies.
   9  -
  10  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  11  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  12  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  13  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  14  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  15  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  16  - PERFORMANCE OF THIS SOFTWARE.
  17 -->
  18
  19 <!-- $Id: dnssec-keygen.docbook,v 1.3.12.6 2004/06/11 01:17:34 marka Exp $ -->
  20
  21 <refentry>
  22   <refentryinfo>
  23     <date>June 30, 2000</date>
  24   </refentryinfo>
  25
  26   <refmeta>
  27     <refentrytitle><application>dnssec-keygen</application></refentrytitle>
  28     <manvolnum>8</manvolnum>
  29     <refmiscinfo>BIND9</refmiscinfo>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname><application>dnssec-keygen</application></refname>
  34     <refpurpose>DNSSEC key generation tool</refpurpose>
  35   </refnamediv>
  36
  37   <refsynopsisdiv>
  38     <cmdsynopsis>
  39       <command>dnssec-keygen</command>
  40       <arg choice="req">-a <replaceable class="parameter">algorithm</replaceable></arg>
  41       <arg choice="req">-b <replaceable class="parameter">keysize</replaceable></arg>
  42       <arg choice="req">-n <replaceable class="parameter">nametype</replaceable></arg>
  43       <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
  44       <arg><option>-e</option></arg>
  45       <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
  46       <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
  47       <arg><option>-h</option></arg>
  48       <arg><option>-k</option></arg>
  49       <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
  50       <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
  51       <arg><option>-s <replaceable class="parameter">strength</replaceable></option></arg>
  52       <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
  53       <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
  54       <arg choice="req">name</arg>
  55     </cmdsynopsis>
  56   </refsynopsisdiv>
  57
  58   <refsect1>
  59     <title>DESCRIPTION</title>
  60     <para>
  61         <command>dnssec-keygen</command> generates keys for DNSSEC
  62         (Secure DNS), as defined in RFC 2535 and RFC &lt;TBA\&gt;.  It can also generate
  63         keys for use with TSIG (Transaction Signatures), as
  64         defined in RFC 2845.
  65     </para>
  66   </refsect1>
  67
  68   <refsect1>
  69     <title>OPTIONS</title>
  70
  71     <variablelist>
  72       <varlistentry>
  73         <term>-a <replaceable class="parameter">algorithm</replaceable></term>
  74         <listitem>
  75           <para>
  76               Selects the cryptographic algorithm.  The value of
  77               <option>algorithm</option> must be one of RSAMD5 (RSA) or RSASHA1,
  78               DSA, DH (Diffie Hellman), or HMAC-MD5.  These values
  79               are case insensitive.
  80           </para>
  81           <para>
  82               Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement algorithm,
  83               and DSA is recommended.  For TSIG, HMAC-MD5 is mandatory.
  84           </para>
  85           <para>
  86               Note 2: HMAC-MD5 and DH automatically set the -k flag.
  87           </para>
  88         </listitem>
  89       </varlistentry>
  90
  91       <varlistentry>
  92         <term>-b <replaceable class="parameter">keysize</replaceable></term>
  93         <listitem>
  94           <para>
  95                Specifies the number of bits in the key.  The choice of key
  96                size depends on the algorithm used.  RSAMD5 / RSASHA1 keys must be between
  97                512 and 2048 bits.  Diffie Hellman keys must be between
  98                128 and 4096 bits.  DSA keys must be between 512 and 1024
  99                bits and an exact multiple of 64.  HMAC-MD5 keys must be
 100                between 1 and 512 bits.
 101           </para>
 102         </listitem>
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term>-n <replaceable class="parameter">nametype</replaceable></term>
 107         <listitem>
 108           <para>
 109                Specifies the owner type of the key.  The value of
 110                <option>nametype</option> must either be ZONE (for a DNSSEC
 111                zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)),
 112                USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).  These values are
 113                case insensitive.
 114           </para>
 115         </listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term>-c <replaceable class="parameter">class</replaceable></term>
 120         <listitem>
 121           <para>
 122                Indicates that the DNS record containing the key should have
 123                the specified class.  If not specified, class IN is used.
 124           </para>
 125         </listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term>-e</term>
 130         <listitem>
 131           <para>
 132                If generating an RSAMD5/RSASHA1 key, use a large exponent.
 133           </para>
 134         </listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term>-f <replaceable class="parameter">flag</replaceable></term>
 139         <listitem>
 140           <para>
 141                 Set the specified flag in the flag field of the KEY/DNSKEY record.
 142                 The only recognized flag is KSK (Key Signing Key) DNSKEY.
 143           </para>
 144         </listitem>
 145       </varlistentry>
 146
 147       <varlistentry>
 148         <term>-g <replaceable class="parameter">generator</replaceable></term>
 149         <listitem>
 150           <para>
 151                If generating a Diffie Hellman key, use this generator.
 152                Allowed values are 2 and 5.  If no generator
 153                is specified, a known prime from RFC 2539 will be used
 154                if possible; otherwise the default is 2.
 155           </para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term>-h</term>
 161         <listitem>
 162           <para>
 163                Prints a short summary of the options and arguments to
 164                <command>dnssec-keygen</command>.
 165           </para>
 166         </listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term>-k</term>
 171         <listitem>
 172           <para>
 173                Generate KEY records rather than DNSKEY records.
 174           </para>
 175         </listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term>-p <replaceable class="parameter">protocol</replaceable></term>
 180         <listitem>
 181           <para>
 182                Sets the protocol value for the generated key.  The protocol
 183                is a number between 0 and 255.  The default is 3 (DNSSEC).
 184                Other possible values for this argument are listed in
 185                RFC 2535 and its successors.
 186           </para>
 187         </listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term>-r <replaceable class="parameter">randomdev</replaceable></term>
 192         <listitem>
 193           <para>
 194                Specifies the source of randomness.  If the operating
 195                system does not provide a <filename>/dev/random</filename>
 196                or equivalent device, the default source of randomness
 197                is keyboard input.  <filename>randomdev</filename> specifies
 198                the name of a character device or file containing random
 199                data to be used instead of the default.  The special value
 200                <filename>keyboard</filename> indicates that keyboard
 201                input should be used.
 202           </para>
 203         </listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term>-s <replaceable class="parameter">strength</replaceable></term>
 208         <listitem>
 209           <para>
 210                Specifies the strength value of the key.  The strength is
 211                a number between 0 and 15, and currently has no defined
 212                purpose in DNSSEC.
 213           </para>
 214         </listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term>-t <replaceable class="parameter">type</replaceable></term>
 219         <listitem>
 220           <para>
 221                Indicates the use of the key.  <option>type</option> must be
 222                one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
 223                is AUTHCONF.  AUTH refers to the ability to authenticate
 224                data, and CONF the ability to encrypt data.
 225           </para>
 226         </listitem>
 227       </varlistentry>
 228
 229       <varlistentry>
 230         <term>-v <replaceable class="parameter">level</replaceable></term>
 231         <listitem>
 232           <para>
 233                Sets the debugging level.
 234           </para>
 235         </listitem>
 236       </varlistentry>
 237
 238     </variablelist>
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>GENERATED KEYS</title>
 243     <para>
 244         When <command>dnssec-keygen</command> completes successfully,
 245         it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
 246         to the standard output.  This is an identification string for
 247         the key it has generated.  These strings can be used as arguments
 248         to <command>dnssec-makekeyset</command>.
 249     </para>
 250     <itemizedlist>
 251       <listitem>
 252         <para>
 253           <filename>nnnn</filename> is the key name.
 254         </para>
 255       </listitem>
 256       <listitem>
 257         <para>
 258           <filename>aaa</filename> is the numeric representation of the
 259           algorithm.
 260         </para>
 261       </listitem>
 262       <listitem>
 263         <para>
 264           <filename>iiiii</filename> is the key identifier (or footprint).
 265         </para>
 266       </listitem>
 267     </itemizedlist>
 268     <para>
 269         <command>dnssec-keygen</command> creates two file, with names based
 270         on the printed string.  <filename>Knnnn.+aaa+iiiii.key</filename>
 271         contains the public key, and
 272         <filename>Knnnn.+aaa+iiiii.private</filename> contains the private
 273         key.
 274     </para>
 275     <para>
 276         The <filename>.key</filename> file contains a DNS KEY record that
 277         can be inserted into a zone file (directly or with a $INCLUDE
 278         statement).
 279     </para>
 280     <para>
 281         The <filename>.private</filename> file contains algorithm specific
 282         fields.  For obvious security reasons, this file does not have
 283         general read permission.
 284     </para>
 285     <para>
 286         Both <filename>.key</filename> and <filename>.private</filename>
 287         files are generated for symmetric encryption algorithm such as
 288         HMAC-MD5, even though the public and private key are equivalent.
 289     </para>
 290   </refsect1>
 291
 292   <refsect1>
 293     <title>EXAMPLE</title>
 294     <para>
 295         To generate a 768-bit DSA key for the domain
 296         <userinput>example.com</userinput>, the following command would be
 297         issued:
 298     </para>
 299     <para>
 300         <userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
 301     </para>
 302     <para>
 303         The command would print a string of the form:
 304     </para>
 305     <para>
 306         <userinput>Kexample.com.+003+26160</userinput>
 307     </para>
 308     <para>
 309         In this example, <command>dnssec-keygen</command> creates
 310         the files <filename>Kexample.com.+003+26160.key</filename> and
 311         <filename>Kexample.com.+003+26160.private</filename>
 312     </para>
 313   </refsect1>
 314
 315   <refsect1>
 316     <title>SEE ALSO</title>
 317     <para>
 318       <citerefentry>
 319         <refentrytitle>dnssec-signzone</refentrytitle>
 320         <manvolnum>8</manvolnum>
 321       </citerefentry>,
 322       <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
 323       <citetitle>RFC 2535</citetitle>,
 324       <citetitle>RFC 2845</citetitle>,
 325       <citetitle>RFC 2539</citetitle>.
 326     </para>
 327   </refsect1>
 328
 329   <refsect1>
 330     <title>AUTHOR</title>
 331     <para>
 332         <corpauthor>Internet Systems Consortium</corpauthor>
 333     </para>
 334   </refsect1>
 335
 336 </refentry>
 337
 338 <!--
 339  - Local variables:
 340  - mode: sgml
 341  - End:
 342 -->