dnssec-keygen.docbook 12.4 KB
Newer Older
1 2
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3
	       [<!ENTITY mdash "&#8212;">]>
Brian Wellington's avatar
Brian Wellington committed
4
<!--
Automatic Updater's avatar
Automatic Updater committed
5
 - Copyright (C) 2004, 2005, 2007, 2008  Internet Systems Consortium, Inc. ("ISC")
6
 - Copyright (C) 2000-2003  Internet Software Consortium.
Brian Wellington's avatar
Brian Wellington committed
7
 -
Automatic Updater's avatar
Automatic Updater committed
8
 - Permission to use, copy, modify, and/or distribute this software for any
Brian Wellington's avatar
Brian Wellington committed
9 10 11
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
Mark Andrews's avatar
Mark Andrews committed
12 13 14 15 16 17 18
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
Brian Wellington's avatar
Brian Wellington committed
19
-->
Mark Andrews's avatar
Mark Andrews committed
20

21
<!-- $Id: dnssec-keygen.docbook,v 1.23 2009/06/17 06:51:43 each Exp $ -->
22
<refentry id="man.dnssec-keygen">
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
  <refentryinfo>
    <date>June 30, 2000</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle><application>dnssec-keygen</application></refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND9</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname><application>dnssec-keygen</application></refname>
    <refpurpose>DNSSEC key generation tool</refpurpose>
  </refnamediv>

38 39 40 41
  <docinfo>
    <copyright>
      <year>2004</year>
      <year>2005</year>
Mark Andrews's avatar
Mark Andrews committed
42
      <year>2007</year>
Automatic Updater's avatar
Automatic Updater committed
43
      <year>2008</year>
44 45 46 47 48 49 50
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
    <copyright>
      <year>2000</year>
      <year>2001</year>
      <year>2002</year>
      <year>2003</year>
Mark Andrews's avatar
Mark Andrews committed
51
      <holder>Internet Software Consortium.</holder>
52 53 54
    </copyright>
  </docinfo>

55 56 57
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>dnssec-keygen</command>
58 59 60
      <arg><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
      <arg ><option>-b <replaceable class="parameter">keysize</replaceable></option></arg>
      <arg><option>-n <replaceable class="parameter">nametype</replaceable></option></arg>
61 62
      <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
      <arg><option>-e</option></arg>
63
      <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
64 65
      <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
      <arg><option>-h</option></arg>
66
      <arg><option>-k</option></arg>
67 68 69 70 71 72 73 74 75 76 77
      <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
      <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
      <arg><option>-s <replaceable class="parameter">strength</replaceable></option></arg>
      <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
      <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
      <arg choice="req">name</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
78 79
    <para><command>dnssec-keygen</command>
      generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
80
      and RFC 4034.  It can also generate keys for use with
81
      TSIG (Transaction Signatures), as defined in RFC 2845.
82 83 84 85 86 87 88 89 90
    </para>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term>-a <replaceable class="parameter">algorithm</replaceable></term>
91 92 93 94
        <listitem>
          <para>
            Selects the cryptographic algorithm.  The value of
            <option>algorithm</option> must be one of RSAMD5 (RSA) or RSASHA1,
95
	    DSA, NSEC3RSASHA1, NSEC3DSA, DH (Diffie Hellman), or HMAC-MD5.
96 97
	    These values are case insensitive.  The default is RSASHA1 for
            DNSSEC key generation.
98 99 100
          </para>
          <para>
            Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
101 102
            algorithm, and DSA is recommended.  For TSIG, HMAC-MD5 is
	    mandatory.
103 104 105 106 107
          </para>
          <para>
            Note 2: HMAC-MD5 and DH automatically set the -k flag.
          </para>
        </listitem>
108 109 110 111
      </varlistentry>

      <varlistentry>
        <term>-b <replaceable class="parameter">keysize</replaceable></term>
112 113 114 115
        <listitem>
          <para>
            Specifies the number of bits in the key.  The choice of key
            size depends on the algorithm used.  RSAMD5 / RSASHA1 keys must be
116
            between 512 and 2048 bits.  Diffie Hellman keys must be between
117 118 119 120
            128 and 4096 bits.  DSA keys must be between 512 and 1024
            bits and an exact multiple of 64.  HMAC-MD5 keys must be
            between 1 and 512 bits.
          </para>
121 122 123 124
            When generating a DNSSEC key with the default algorithm, this
            value defaults to 1024, or 2048 if the KSK flag is set.
          <para>
          </para>
125
        </listitem>
126 127 128 129
      </varlistentry>

      <varlistentry>
        <term>-n <replaceable class="parameter">nametype</replaceable></term>
130 131 132 133 134 135 136
        <listitem>
          <para>
            Specifies the owner type of the key.  The value of
            <option>nametype</option> must either be ZONE (for a DNSSEC
            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).
137 138
            These values are case insensitive.  Defaults to ZONE for DNSKEY
	    generation.
139 140
          </para>
        </listitem>
141 142 143 144
      </varlistentry>

      <varlistentry>
        <term>-c <replaceable class="parameter">class</replaceable></term>
145 146 147 148 149 150
        <listitem>
          <para>
            Indicates that the DNS record containing the key should have
            the specified class.  If not specified, class IN is used.
          </para>
        </listitem>
151 152 153 154
      </varlistentry>

      <varlistentry>
        <term>-e</term>
155 156 157 158 159
        <listitem>
          <para>
            If generating an RSAMD5/RSASHA1 key, use a large exponent.
          </para>
        </listitem>
160 161
      </varlistentry>

162 163
      <varlistentry>
        <term>-f <replaceable class="parameter">flag</replaceable></term>
164 165 166
        <listitem>
          <para>
            Set the specified flag in the flag field of the KEY/DNSKEY record.
167
    	    The only recognized flag is KSK (Key Signing Key) DNSKEY.
168 169
          </para>
        </listitem>
170 171
      </varlistentry>

172 173
      <varlistentry>
        <term>-g <replaceable class="parameter">generator</replaceable></term>
174 175 176 177 178 179 180 181
        <listitem>
          <para>
            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.
          </para>
        </listitem>
182 183 184 185
      </varlistentry>

      <varlistentry>
        <term>-h</term>
186 187 188 189 190 191
        <listitem>
          <para>
            Prints a short summary of the options and arguments to
            <command>dnssec-keygen</command>.
          </para>
        </listitem>
192 193
      </varlistentry>

194 195
      <varlistentry>
        <term>-k</term>
196 197 198 199 200
        <listitem>
          <para>
            Generate KEY records rather than DNSKEY records.
          </para>
        </listitem>
201 202
      </varlistentry>

203 204
      <varlistentry>
        <term>-p <replaceable class="parameter">protocol</replaceable></term>
205 206 207 208 209 210 211 212
        <listitem>
          <para>
            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.
          </para>
        </listitem>
213 214 215 216
      </varlistentry>

      <varlistentry>
        <term>-r <replaceable class="parameter">randomdev</replaceable></term>
217 218 219 220 221 222 223 224 225 226 227 228 229
        <listitem>
          <para>
            Specifies the source of randomness.  If the operating
            system does not provide a <filename>/dev/random</filename>
            or equivalent device, the default source of randomness
            is keyboard input.  <filename>randomdev</filename>
            specifies
            the name of a character device or file containing random
            data to be used instead of the default.  The special value
            <filename>keyboard</filename> indicates that keyboard
            input should be used.
          </para>
        </listitem>
230 231 232 233
      </varlistentry>

      <varlistentry>
        <term>-s <replaceable class="parameter">strength</replaceable></term>
234 235 236 237 238 239 240
        <listitem>
          <para>
            Specifies the strength value of the key.  The strength is
            a number between 0 and 15, and currently has no defined
            purpose in DNSSEC.
          </para>
        </listitem>
241 242 243 244
      </varlistentry>

      <varlistentry>
        <term>-t <replaceable class="parameter">type</replaceable></term>
245 246 247 248 249 250 251 252
        <listitem>
          <para>
            Indicates the use of the key.  <option>type</option> 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.
          </para>
        </listitem>
253 254 255 256
      </varlistentry>

      <varlistentry>
        <term>-v <replaceable class="parameter">level</replaceable></term>
257 258 259 260 261
        <listitem>
          <para>
            Sets the debugging level.
          </para>
        </listitem>
262 263 264 265 266 267 268 269
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>GENERATED KEYS</title>
    <para>
270 271 272 273
      When <command>dnssec-keygen</command> completes
      successfully,
      it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
      to the standard output.  This is an identification string for
Mark Andrews's avatar
Mark Andrews committed
274
      the key it has generated.
275
    </para>
Brian Wellington's avatar
Brian Wellington committed
276 277
    <itemizedlist>
      <listitem>
278
        <para><filename>nnnn</filename> is the key name.
Brian Wellington's avatar
Brian Wellington committed
279 280 281
        </para>
      </listitem>
      <listitem>
282 283
        <para><filename>aaa</filename> is the numeric representation
          of the
Brian Wellington's avatar
Brian Wellington committed
284 285 286 287
          algorithm.
        </para>
      </listitem>
      <listitem>
288 289
        <para><filename>iiiii</filename> is the key identifier (or
          footprint).
Brian Wellington's avatar
Brian Wellington committed
290 291 292
        </para>
      </listitem>
    </itemizedlist>
293
    <para><command>dnssec-keygen</command> 
294
      creates two files, with names based
295 296 297 298 299
      on the printed string.  <filename>Knnnn.+aaa+iiiii.key</filename>
      contains the public key, and
      <filename>Knnnn.+aaa+iiiii.private</filename> contains the
      private
      key.
300 301
    </para>
    <para>
302 303 304 305
      The <filename>.key</filename> file contains a DNS KEY record
      that
      can be inserted into a zone file (directly or with a $INCLUDE
      statement).
306 307
    </para>
    <para>
308 309
      The <filename>.private</filename> file contains
      algorithm-specific
310 311
      fields.  For obvious security reasons, this file does not have
      general read permission.
312 313
    </para>
    <para>
314
      Both <filename>.key</filename> and <filename>.private</filename>
315
      files are generated for symmetric encryption algorithms such as
316
      HMAC-MD5, even though the public and private key are equivalent.
317 318 319 320 321 322
    </para>
  </refsect1>

  <refsect1>
    <title>EXAMPLE</title>
    <para>
323 324 325
      To generate a 768-bit DSA key for the domain
      <userinput>example.com</userinput>, the following command would be
      issued:
326
    </para>
327
    <para><userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
328 329
    </para>
    <para>
330
      The command would print a string of the form:
331
    </para>
332
    <para><userinput>Kexample.com.+003+26160</userinput>
333 334
    </para>
    <para>
335 336 337
      In this example, <command>dnssec-keygen</command> creates
      the files <filename>Kexample.com.+003+26160.key</filename>
      and
338
      <filename>Kexample.com.+003+26160.private</filename>.
339 340 341 342 343
    </para>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
344 345
    <para><citerefentry>
        <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
346 347
      </citerefentry>,
      <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
348
      <citetitle>RFC 2539</citetitle>,
349
      <citetitle>RFC 2845</citetitle>,
350
      <citetitle>RFC 4033</citetitle>.
351 352 353 354 355
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
356
    <para><corpauthor>Internet Systems Consortium</corpauthor>
357 358 359
    </para>
  </refsect1>

360
</refentry><!--
361 362 363 364
 - Local variables:
 - mode: sgml
 - End:
-->