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

   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  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.7.18.11 2007/08/28 07:20:00 tbox 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       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  44     </copyright>
  45     <copyright>
  46       <year>2000</year>
  47       <year>2001</year>
  48       <year>2002</year>
  49       <year>2003</year>
  50       <holder>Internet Software Consortium.</holder>
  51     </copyright>
  52   </docinfo>
  53
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>dnssec-keygen</command>
  57       <arg choice="req">-a <replaceable class="parameter">algorithm</replaceable></arg>
  58       <arg choice="req">-b <replaceable class="parameter">keysize</replaceable></arg>
  59       <arg choice="req">-n <replaceable class="parameter">nametype</replaceable></arg>
  60       <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
  61       <arg><option>-e</option></arg>
  62       <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
  63       <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
  64       <arg><option>-h</option></arg>
  65       <arg><option>-k</option></arg>
  66       <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
  67       <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
  68       <arg><option>-s <replaceable class="parameter">strength</replaceable></option></arg>
  69       <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
  70       <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
  71       <arg choice="req">name</arg>
  72     </cmdsynopsis>
  73   </refsynopsisdiv>
  74
  75   <refsect1>
  76     <title>DESCRIPTION</title>
  77     <para><command>dnssec-keygen</command>
  78       generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
  79       and RFC 4034.  It can also generate keys for use with
  80       TSIG (Transaction Signatures), as defined in RFC 2845.
  81     </para>
  82   </refsect1>
  83
  84   <refsect1>
  85     <title>OPTIONS</title>
  86
  87     <variablelist>
  88       <varlistentry>
  89         <term>-a <replaceable class="parameter">algorithm</replaceable></term>
  90         <listitem>
  91           <para>
  92             Selects the cryptographic algorithm.  The value of
  93             <option>algorithm</option> must be one of RSAMD5 (RSA) or RSASHA1,
  94                       DSA, DH (Diffie Hellman), or HMAC-MD5.  These values
  95             are case insensitive.
  96           </para>
  97           <para>
  98             Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
  99             algorithm,
 100             and DSA is recommended.  For TSIG, HMAC-MD5 is mandatory.
 101           </para>
 102           <para>
 103             Note 2: HMAC-MD5 and DH automatically set the -k flag.
 104           </para>
 105         </listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term>-b <replaceable class="parameter">keysize</replaceable></term>
 110         <listitem>
 111           <para>
 112             Specifies the number of bits in the key.  The choice of key
 113             size depends on the algorithm used.  RSAMD5 / RSASHA1 keys must be
 114             between
 115             512 and 2048 bits.  Diffie Hellman keys must be between
 116             128 and 4096 bits.  DSA keys must be between 512 and 1024
 117             bits and an exact multiple of 64.  HMAC-MD5 keys must be
 118             between 1 and 512 bits.
 119           </para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term>-n <replaceable class="parameter">nametype</replaceable></term>
 125         <listitem>
 126           <para>
 127             Specifies the owner type of the key.  The value of
 128             <option>nametype</option> must either be ZONE (for a DNSSEC
 129             zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
 130             a host (KEY)),
 131             USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
 132             These values are
 133             case insensitive.
 134           </para>
 135         </listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term>-c <replaceable class="parameter">class</replaceable></term>
 140         <listitem>
 141           <para>
 142             Indicates that the DNS record containing the key should have
 143             the specified class.  If not specified, class IN is used.
 144           </para>
 145         </listitem>
 146       </varlistentry>
 147
 148       <varlistentry>
 149         <term>-e</term>
 150         <listitem>
 151           <para>
 152             If generating an RSAMD5/RSASHA1 key, use a large exponent.
 153           </para>
 154         </listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term>-f <replaceable class="parameter">flag</replaceable></term>
 159         <listitem>
 160           <para>
 161             Set the specified flag in the flag field of the KEY/DNSKEY record.
 162                         The only recognized flag is KSK (Key Signing Key) DNSKEY.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term>-g <replaceable class="parameter">generator</replaceable></term>
 169         <listitem>
 170           <para>
 171             If generating a Diffie Hellman key, use this generator.
 172             Allowed values are 2 and 5.  If no generator
 173             is specified, a known prime from RFC 2539 will be used
 174             if possible; otherwise the default is 2.
 175           </para>
 176         </listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term>-h</term>
 181         <listitem>
 182           <para>
 183             Prints a short summary of the options and arguments to
 184             <command>dnssec-keygen</command>.
 185           </para>
 186         </listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term>-k</term>
 191         <listitem>
 192           <para>
 193             Generate KEY records rather than DNSKEY records.
 194           </para>
 195         </listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term>-p <replaceable class="parameter">protocol</replaceable></term>
 200         <listitem>
 201           <para>
 202             Sets the protocol value for the generated key.  The protocol
 203             is a number between 0 and 255.  The default is 3 (DNSSEC).
 204             Other possible values for this argument are listed in
 205             RFC 2535 and its successors.
 206           </para>
 207         </listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term>-r <replaceable class="parameter">randomdev</replaceable></term>
 212         <listitem>
 213           <para>
 214             Specifies the source of randomness.  If the operating
 215             system does not provide a <filename>/dev/random</filename>
 216             or equivalent device, the default source of randomness
 217             is keyboard input.  <filename>randomdev</filename>
 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             <filename>keyboard</filename> indicates that keyboard
 222             input should be used.
 223           </para>
 224         </listitem>
 225       </varlistentry>
 226
 227       <varlistentry>
 228         <term>-s <replaceable class="parameter">strength</replaceable></term>
 229         <listitem>
 230           <para>
 231             Specifies the strength value of the key.  The strength is
 232             a number between 0 and 15, and currently has no defined
 233             purpose in DNSSEC.
 234           </para>
 235         </listitem>
 236       </varlistentry>
 237
 238       <varlistentry>
 239         <term>-t <replaceable class="parameter">type</replaceable></term>
 240         <listitem>
 241           <para>
 242             Indicates the use of the key.  <option>type</option> must be
 243             one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
 244             is AUTHCONF.  AUTH refers to the ability to authenticate
 245             data, and CONF the ability to encrypt data.
 246           </para>
 247         </listitem>
 248       </varlistentry>
 249
 250       <varlistentry>
 251         <term>-v <replaceable class="parameter">level</replaceable></term>
 252         <listitem>
 253           <para>
 254             Sets the debugging level.
 255           </para>
 256         </listitem>
 257       </varlistentry>
 258
 259     </variablelist>
 260   </refsect1>
 261
 262   <refsect1>
 263     <title>GENERATED KEYS</title>
 264     <para>
 265       When <command>dnssec-keygen</command> completes
 266       successfully,
 267       it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
 268       to the standard output.  This is an identification string for
 269       the key it has generated.
 270     </para>
 271     <itemizedlist>
 272       <listitem>
 273         <para><filename>nnnn</filename> is the key name.
 274         </para>
 275       </listitem>
 276       <listitem>
 277         <para><filename>aaa</filename> is the numeric representation
 278           of the
 279           algorithm.
 280         </para>
 281       </listitem>
 282       <listitem>
 283         <para><filename>iiiii</filename> is the key identifier (or
 284           footprint).
 285         </para>
 286       </listitem>
 287     </itemizedlist>
 288     <para><command>dnssec-keygen</command>
 289       creates two files, with names based
 290       on the printed string.  <filename>Knnnn.+aaa+iiiii.key</filename>
 291       contains the public key, and
 292       <filename>Knnnn.+aaa+iiiii.private</filename> contains the
 293       private
 294       key.
 295     </para>
 296     <para>
 297       The <filename>.key</filename> file contains a DNS KEY record
 298       that
 299       can be inserted into a zone file (directly or with a $INCLUDE
 300       statement).
 301     </para>
 302     <para>
 303       The <filename>.private</filename> file contains
 304       algorithm-specific
 305       fields.  For obvious security reasons, this file does not have
 306       general read permission.
 307     </para>
 308     <para>
 309       Both <filename>.key</filename> and <filename>.private</filename>
 310       files are generated for symmetric encryption algorithms such as
 311       HMAC-MD5, even though the public and private key are equivalent.
 312     </para>
 313   </refsect1>
 314
 315   <refsect1>
 316     <title>EXAMPLE</title>
 317     <para>
 318       To generate a 768-bit DSA key for the domain
 319       <userinput>example.com</userinput>, the following command would be
 320       issued:
 321     </para>
 322     <para><userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
 323     </para>
 324     <para>
 325       The command would print a string of the form:
 326     </para>
 327     <para><userinput>Kexample.com.+003+26160</userinput>
 328     </para>
 329     <para>
 330       In this example, <command>dnssec-keygen</command> creates
 331       the files <filename>Kexample.com.+003+26160.key</filename>
 332       and
 333       <filename>Kexample.com.+003+26160.private</filename>.
 334     </para>
 335   </refsect1>
 336
 337   <refsect1>
 338     <title>SEE ALSO</title>
 339     <para><citerefentry>
 340         <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
 341       </citerefentry>,
 342       <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
 343       <citetitle>RFC 2535</citetitle>,
 344       <citetitle>RFC 2845</citetitle>,
 345       <citetitle>RFC 2539</citetitle>.
 346     </para>
 347   </refsect1>
 348
 349   <refsect1>
 350     <title>AUTHOR</title>
 351     <para><corpauthor>Internet Systems Consortium</corpauthor>
 352     </para>
 353   </refsect1>
 354
 355 </refentry><!--
 356  - Local variables:
 357  - mode: sgml
 358  - End:
 359 -->