contrib/bind9/bin/dnssec/dnssec-keyfromlabel.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) 2008-2012  Internet Systems Consortium, Inc. ("ISC")
   6  -
   7  - Permission to use, copy, modify, and/or distribute this software for any
   8  - purpose with or without fee is hereby granted, provided that the above
   9  - copyright notice and this permission notice appear in all copies.
  10  -
  11  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17  - PERFORMANCE OF THIS SOFTWARE.
  18 -->
  19
  20 <!-- $Id: dnssec-keyfromlabel.docbook,v 1.18.14.2 2011/02/28 01:19:58 tbox Exp $ -->
  21 <refentry id="man.dnssec-keyfromlabel">
  22   <refentryinfo>
  23     <date>February 8, 2008</date>
  24   </refentryinfo>
  25
  26   <refmeta>
  27     <refentrytitle><application>dnssec-keyfromlabel</application></refentrytitle>
  28     <manvolnum>8</manvolnum>
  29     <refmiscinfo>BIND9</refmiscinfo>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname><application>dnssec-keyfromlabel</application></refname>
  34     <refpurpose>DNSSEC key generation tool</refpurpose>
  35   </refnamediv>
  36
  37   <docinfo>
  38     <copyright>
  39       <year>2008</year>
  40       <year>2009</year>
  41       <year>2010</year>
  42       <year>2011</year>
  43       <year>2012</year>
  44       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  45     </copyright>
  46   </docinfo>
  47
  48   <refsynopsisdiv>
  49     <cmdsynopsis>
  50       <command>dnssec-keyfromlabel</command>
  51       <arg choice="req">-l <replaceable class="parameter">label</replaceable></arg>
  52       <arg><option>-3</option></arg>
  53       <arg><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
  54       <arg><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
  55       <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
  56       <arg><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
  57       <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
  58       <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
  59       <arg><option>-G</option></arg>
  60       <arg><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
  61       <arg><option>-k</option></arg>
  62       <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
  63       <arg><option>-n <replaceable class="parameter">nametype</replaceable></option></arg>
  64       <arg><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
  65       <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
  66       <arg><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
  67       <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
  68       <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
  69       <arg><option>-y</option></arg>
  70       <arg choice="req">name</arg>
  71     </cmdsynopsis>
  72   </refsynopsisdiv>
  73
  74   <refsect1>
  75     <title>DESCRIPTION</title>
  76     <para><command>dnssec-keyfromlabel</command>
  77       gets keys with the given label from a crypto hardware and builds
  78       key files for DNSSEC (Secure DNS), as defined in RFC 2535
  79       and RFC 4034.
  80     </para>
  81     <para>
  82       The <option>name</option> of the key is specified on the command
  83       line.  This must match the name of the zone for which the key is
  84       being generated.
  85     </para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>OPTIONS</title>
  90
  91     <variablelist>
  92       <varlistentry>
  93         <term>-a <replaceable class="parameter">algorithm</replaceable></term>
  94         <listitem>
  95           <para>
  96             Selects the cryptographic algorithm.  The value of
  97             <option>algorithm</option> must be one of RSAMD5, RSASHA1,
  98             DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512, ECCGOST,
  99             ECDSAP256SHA256 or ECDSAP384SHA384.
 100             These values are case insensitive.
 101           </para>
 102           <para>
 103             If no algorithm is specified, then RSASHA1 will be used by
 104             default, unless the <option>-3</option> option is specified,
 105             in which case NSEC3RSASHA1 will be used instead.  (If
 106             <option>-3</option> is used and an algorithm is specified,
 107             that algorithm will be checked for compatibility with NSEC3.)
 108           </para>
 109           <para>
 110             Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
 111             algorithm, and DSA is recommended.
 112           </para>
 113           <para>
 114             Note 2: DH automatically sets the -k flag.
 115           </para>
 116         </listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term>-3</term>
 121         <listitem>
 122           <para>
 123             Use an NSEC3-capable algorithm to generate a DNSSEC key.
 124             If this option is used and no algorithm is explicitly
 125             set on the command line, NSEC3RSASHA1 will be used by
 126             default.
 127           </para>
 128         </listitem>
 129       </varlistentry>
 130
 131       <varlistentry>
 132         <term>-E <replaceable class="parameter">engine</replaceable></term>
 133         <listitem>
 134           <para>
 135             Specifies the name of the crypto hardware (OpenSSL engine).
 136             When compiled with PKCS#11 support it defaults to "pkcs11".
 137           </para>
 138         </listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term>-l <replaceable class="parameter">label</replaceable></term>
 143         <listitem>
 144           <para>
 145             Specifies the label of the key pair in the crypto hardware.
 146             The label may be preceded by an optional OpenSSL engine name,
 147             separated by a colon, as in "pkcs11:keylabel".
 148           </para>
 149         </listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term>-n <replaceable class="parameter">nametype</replaceable></term>
 154         <listitem>
 155           <para>
 156             Specifies the owner type of the key.  The value of
 157             <option>nametype</option> must either be ZONE (for a DNSSEC
 158             zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
 159             a host (KEY)),
 160             USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
 161             These values are case insensitive.
 162           </para>
 163         </listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term>-C</term>
 168         <listitem>
 169           <para>
 170             Compatibility mode:  generates an old-style key, without
 171             any metadata.  By default, <command>dnssec-keyfromlabel</command>
 172             will include the key's creation date in the metadata stored
 173             with the private key, and other dates may be set there as well
 174             (publication date, activation date, etc).  Keys that include
 175             this data may be incompatible with older versions of BIND; the
 176             <option>-C</option> option suppresses them.
 177           </para>
 178         </listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term>-c <replaceable class="parameter">class</replaceable></term>
 183         <listitem>
 184           <para>
 185             Indicates that the DNS record containing the key should have
 186             the specified class.  If not specified, class IN is used.
 187           </para>
 188         </listitem>
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term>-f <replaceable class="parameter">flag</replaceable></term>
 193         <listitem>
 194           <para>
 195             Set the specified flag in the flag field of the KEY/DNSKEY record.
 196             The only recognized flags are KSK (Key Signing Key) and REVOKE.
 197           </para>
 198         </listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term>-G</term>
 203         <listitem>
 204           <para>
 205             Generate a key, but do not publish it or sign with it.  This
 206             option is incompatible with -P and -A.
 207           </para>
 208         </listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term>-h</term>
 213         <listitem>
 214           <para>
 215             Prints a short summary of the options and arguments to
 216             <command>dnssec-keyfromlabel</command>.
 217           </para>
 218         </listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term>-K <replaceable class="parameter">directory</replaceable></term>
 223         <listitem>
 224           <para>
 225             Sets the directory in which the key files are to be written.
 226           </para>
 227         </listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term>-k</term>
 232         <listitem>
 233           <para>
 234             Generate KEY records rather than DNSKEY records.
 235           </para>
 236         </listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term>-p <replaceable class="parameter">protocol</replaceable></term>
 241         <listitem>
 242           <para>
 243             Sets the protocol value for the key.  The protocol
 244             is a number between 0 and 255.  The default is 3 (DNSSEC).
 245             Other possible values for this argument are listed in
 246             RFC 2535 and its successors.
 247           </para>
 248         </listitem>
 249       </varlistentry>
 250
 251       <varlistentry>
 252         <term>-t <replaceable class="parameter">type</replaceable></term>
 253         <listitem>
 254           <para>
 255             Indicates the use of the key.  <option>type</option> must be
 256             one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
 257             is AUTHCONF.  AUTH refers to the ability to authenticate
 258             data, and CONF the ability to encrypt data.
 259           </para>
 260         </listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term>-v <replaceable class="parameter">level</replaceable></term>
 265         <listitem>
 266           <para>
 267             Sets the debugging level.
 268           </para>
 269         </listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term>-y</term>
 274         <listitem>
 275           <para>
 276             Allows DNSSEC key files to be generated even if the key ID
 277             would collide with that of an existing key, in the event of
 278             either key being revoked.  (This is only safe to use if you
 279             are sure you won't be using RFC 5011 trust anchor maintenance
 280             with either of the keys involved.)
 281           </para>
 282         </listitem>
 283       </varlistentry>
 284
 285     </variablelist>
 286   </refsect1>
 287
 288   <refsect1>
 289     <title>TIMING OPTIONS</title>
 290
 291     <para>
 292       Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
 293       If the argument begins with a '+' or '-', it is interpreted as
 294       an offset from the present time.  For convenience, if such an offset
 295       is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
 296       then the offset is computed in years (defined as 365 24-hour days,
 297       ignoring leap years), months (defined as 30 24-hour days), weeks,
 298       days, hours, or minutes, respectively.  Without a suffix, the offset
 299       is computed in seconds.
 300     </para>
 301
 302     <variablelist>
 303       <varlistentry>
 304         <term>-P <replaceable class="parameter">date/offset</replaceable></term>
 305         <listitem>
 306           <para>
 307             Sets the date on which a key is to be published to the zone.
 308             After that date, the key will be included in the zone but will
 309             not be used to sign it.  If not set, and if the -G option has
 310             not been used, the default is "now".
 311           </para>
 312         </listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term>-A <replaceable class="parameter">date/offset</replaceable></term>
 317         <listitem>
 318           <para>
 319             Sets the date on which the key is to be activated.  After that
 320             date, the key will be included in the zone and used to sign
 321             it.  If not set, and if the -G option has not been used, the
 322             default is "now".
 323           </para>
 324         </listitem>
 325       </varlistentry>
 326
 327       <varlistentry>
 328         <term>-R <replaceable class="parameter">date/offset</replaceable></term>
 329         <listitem>
 330           <para>
 331             Sets the date on which the key is to be revoked.  After that
 332             date, the key will be flagged as revoked.  It will be included
 333             in the zone and will be used to sign it.
 334           </para>
 335         </listitem>
 336       </varlistentry>
 337
 338       <varlistentry>
 339         <term>-I <replaceable class="parameter">date/offset</replaceable></term>
 340         <listitem>
 341           <para>
 342             Sets the date on which the key is to be retired.  After that
 343             date, the key will still be included in the zone, but it
 344             will not be used to sign it.
 345           </para>
 346         </listitem>
 347       </varlistentry>
 348
 349       <varlistentry>
 350         <term>-D <replaceable class="parameter">date/offset</replaceable></term>
 351         <listitem>
 352           <para>
 353             Sets the date on which the key is to be deleted.  After that
 354             date, the key will no longer be included in the zone.  (It
 355             may remain in the key repository, however.)
 356           </para>
 357         </listitem>
 358       </varlistentry>
 359     </variablelist>
 360   </refsect1>
 361
 362   <refsect1>
 363     <title>GENERATED KEY FILES</title>
 364     <para>
 365       When <command>dnssec-keyfromlabel</command> completes
 366       successfully,
 367       it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
 368       to the standard output.  This is an identification string for
 369       the key files it has generated.
 370     </para>
 371     <itemizedlist>
 372       <listitem>
 373         <para><filename>nnnn</filename> is the key name.
 374         </para>
 375       </listitem>
 376       <listitem>
 377         <para><filename>aaa</filename> is the numeric representation
 378           of the algorithm.
 379         </para>
 380       </listitem>
 381       <listitem>
 382         <para><filename>iiiii</filename> is the key identifier (or
 383           footprint).
 384         </para>
 385       </listitem>
 386     </itemizedlist>
 387     <para><command>dnssec-keyfromlabel</command>
 388       creates two files, with names based
 389       on the printed string.  <filename>Knnnn.+aaa+iiiii.key</filename>
 390       contains the public key, and
 391       <filename>Knnnn.+aaa+iiiii.private</filename> contains the
 392       private key.
 393     </para>
 394     <para>
 395       The <filename>.key</filename> file contains a DNS KEY record
 396       that
 397       can be inserted into a zone file (directly or with a $INCLUDE
 398       statement).
 399     </para>
 400     <para>
 401       The <filename>.private</filename> file contains
 402       algorithm-specific
 403       fields.  For obvious security reasons, this file does not have
 404       general read permission.
 405     </para>
 406   </refsect1>
 407
 408   <refsect1>
 409     <title>SEE ALSO</title>
 410     <para><citerefentry>
 411         <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
 412       </citerefentry>,
 413       <citerefentry>
 414         <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
 415       </citerefentry>,
 416       <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
 417       <citetitle>RFC 4034</citetitle>.
 418     </para>
 419   </refsect1>
 420
 421   <refsect1>
 422     <title>AUTHOR</title>
 423     <para><corpauthor>Internet Systems Consortium</corpauthor>
 424     </para>
 425   </refsect1>
 426
 427 </refentry><!--
 428  - Local variables:
 429  - mode: sgml
 430  - End:
 431 -->