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  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.6 2008/11/07 13:54:11 jreed 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       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  41     </copyright>
  42   </docinfo>
  43
  44   <refsynopsisdiv>
  45     <cmdsynopsis>
  46       <command>dnssec-keyfromlabel</command>
  47       <arg choice="req">-a <replaceable class="parameter">algorithm</replaceable></arg>
  48       <arg choice="req">-l <replaceable class="parameter">label</replaceable></arg>
  49       <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
  50       <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
  51       <arg><option>-k</option></arg>
  52       <arg><option>-n <replaceable class="parameter">nametype</replaceable></option></arg>
  53       <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
  54       <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
  55       <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
  56       <arg choice="req">name</arg>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>DESCRIPTION</title>
  62     <para><command>dnssec-keyfromlabel</command>
  63       gets keys with the given label from a crypto hardware and builds
  64       key files for DNSSEC (Secure DNS), as defined in RFC 2535
  65       and RFC 4034.
  66     </para>
  67   </refsect1>
  68
  69   <refsect1>
  70     <title>OPTIONS</title>
  71
  72     <variablelist>
  73       <varlistentry>
  74         <term>-a <replaceable class="parameter">algorithm</replaceable></term>
  75         <listitem>
  76           <para>
  77             Selects the cryptographic algorithm.  The value of
  78             <option>algorithm</option> must be one of RSAMD5 (RSA)
  79             or RSASHA1, DSA, NSEC3RSASHA1, NSEC3DSA or DH (Diffie Hellman).
  80             These values are case insensitive.
  81           </para>
  82           <para>
  83             Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
  84             algorithm, and DSA is recommended.
  85           </para>
  86           <para>
  87             Note 2: DH automatically sets the -k flag.
  88           </para>
  89         </listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term>-l <replaceable class="parameter">label</replaceable></term>
  94         <listitem>
  95           <para>
  96             Specifies the label of keys in the crypto hardware
  97             (PKCS#11 device).
  98           </para>
  99         </listitem>
 100       </varlistentry>
 101
 102       <varlistentry>
 103         <term>-n <replaceable class="parameter">nametype</replaceable></term>
 104         <listitem>
 105           <para>
 106             Specifies the owner type of the key.  The value of
 107             <option>nametype</option> must either be ZONE (for a DNSSEC
 108             zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
 109             a host (KEY)),
 110             USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
 111             These values are
 112             case insensitive.
 113           </para>
 114         </listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term>-c <replaceable class="parameter">class</replaceable></term>
 119         <listitem>
 120           <para>
 121             Indicates that the DNS record containing the key should have
 122             the specified class.  If not specified, class IN is used.
 123           </para>
 124         </listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term>-f <replaceable class="parameter">flag</replaceable></term>
 129         <listitem>
 130           <para>
 131             Set the specified flag in the flag field of the KEY/DNSKEY record.
 132             The only recognized flag is KSK (Key Signing Key) DNSKEY.
 133           </para>
 134         </listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term>-h</term>
 139         <listitem>
 140           <para>
 141             Prints a short summary of the options and arguments to
 142             <command>dnssec-keygen</command>.
 143           </para>
 144         </listitem>
 145       </varlistentry>
 146
 147       <varlistentry>
 148         <term>-k</term>
 149         <listitem>
 150           <para>
 151             Generate KEY records rather than DNSKEY records.
 152           </para>
 153         </listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term>-p <replaceable class="parameter">protocol</replaceable></term>
 158         <listitem>
 159           <para>
 160             Sets the protocol value for the generated key.  The protocol
 161             is a number between 0 and 255.  The default is 3 (DNSSEC).
 162             Other possible values for this argument are listed in
 163             RFC 2535 and its successors.
 164           </para>
 165         </listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term>-t <replaceable class="parameter">type</replaceable></term>
 170         <listitem>
 171           <para>
 172             Indicates the use of the key.  <option>type</option> must be
 173             one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF.  The default
 174             is AUTHCONF.  AUTH refers to the ability to authenticate
 175             data, and CONF the ability to encrypt data.
 176           </para>
 177         </listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term>-v <replaceable class="parameter">level</replaceable></term>
 182         <listitem>
 183           <para>
 184             Sets the debugging level.
 185           </para>
 186         </listitem>
 187       </varlistentry>
 188
 189     </variablelist>
 190   </refsect1>
 191
 192   <refsect1>
 193     <title>GENERATED KEY FILES</title>
 194     <para>
 195       When <command>dnssec-keyfromlabel</command> completes
 196       successfully,
 197       it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
 198       to the standard output.  This is an identification string for
 199       the key files it has generated.
 200     </para>
 201     <itemizedlist>
 202       <listitem>
 203         <para><filename>nnnn</filename> is the key name.
 204         </para>
 205       </listitem>
 206       <listitem>
 207         <para><filename>aaa</filename> is the numeric representation
 208           of the
 209           algorithm.
 210         </para>
 211       </listitem>
 212       <listitem>
 213         <para><filename>iiiii</filename> is the key identifier (or
 214           footprint).
 215         </para>
 216       </listitem>
 217     </itemizedlist>
 218     <para><command>dnssec-keyfromlabel</command>
 219       creates two files, with names based
 220       on the printed string.  <filename>Knnnn.+aaa+iiiii.key</filename>
 221       contains the public key, and
 222       <filename>Knnnn.+aaa+iiiii.private</filename> contains the
 223       private
 224       key.
 225     </para>
 226     <para>
 227       The <filename>.key</filename> file contains a DNS KEY record
 228       that
 229       can be inserted into a zone file (directly or with a $INCLUDE
 230       statement).
 231     </para>
 232     <para>
 233       The <filename>.private</filename> file contains algorithm
 234       specific
 235       fields.  For obvious security reasons, this file does not have
 236       general read permission.
 237     </para>
 238   </refsect1>
 239
 240   <refsect1>
 241     <title>SEE ALSO</title>
 242     <para><citerefentry>
 243         <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
 244       </citerefentry>,
 245       <citerefentry>
 246         <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
 247       </citerefentry>,
 248       <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
 249       <citetitle>RFC 2539</citetitle>,
 250       <citetitle>RFC 2845</citetitle>,
 251       <citetitle>RFC 4033</citetitle>.
 252     </para>
 253   </refsect1>
 254
 255   <refsect1>
 256     <title>AUTHOR</title>
 257     <para><corpauthor>Internet Systems Consortium</corpauthor>
 258     </para>
 259   </refsect1>
 260
 261 </refentry><!--
 262  - Local variables:
 263  - mode: sgml
 264  - End:
 265 -->