dnssec-keyfromlabel.html 13.7 KB
Newer Older
Francis Dupont's avatar
regen  
Francis Dupont committed
1
<!--
Automatic Updater's avatar
Automatic Updater committed
2
 - Copyright (C) 2008-2011 Internet Systems Consortium, Inc. ("ISC")
Francis Dupont's avatar
regen  
Francis Dupont committed
3
 - 
Automatic Updater's avatar
regen  
Automatic Updater committed
4
 - Permission to use, copy, modify, and/or distribute this software for any
Francis Dupont's avatar
regen  
Francis Dupont committed
5 6 7 8 9 10 11 12 13 14 15
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 - 
 - 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.
-->
Tinderbox User's avatar
Tinderbox User committed
16
<!-- $Id$ -->
Francis Dupont's avatar
regen  
Francis Dupont committed
17 18 19 20 21 22 23 24 25 26 27 28 29 30
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>dnssec-keyfromlabel</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
<a name="man.dnssec-keyfromlabel"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>Name</h2>
<p><span class="application">dnssec-keyfromlabel</span> &#8212; DNSSEC key generation tool</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
Automatic Updater's avatar
Automatic Updater committed
31
<div class="cmdsynopsis"><p><code class="command">dnssec-keyfromlabel</code>  {-l <em class="replaceable"><code>label</code></em>} [<code class="option">-3</code>] [<code class="option">-a <em class="replaceable"><code>algorithm</code></em></code>] [<code class="option">-A <em class="replaceable"><code>date/offset</code></em></code>] [<code class="option">-c <em class="replaceable"><code>class</code></em></code>] [<code class="option">-D <em class="replaceable"><code>date/offset</code></em></code>] [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>] [<code class="option">-f <em class="replaceable"><code>flag</code></em></code>] [<code class="option">-G</code>] [<code class="option">-I <em class="replaceable"><code>date/offset</code></em></code>] [<code class="option">-k</code>] [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>] [<code class="option">-n <em class="replaceable"><code>nametype</code></em></code>] [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>] [<code class="option">-p <em class="replaceable"><code>protocol</code></em></code>] [<code class="option">-R <em class="replaceable"><code>date/offset</code></em></code>] [<code class="option">-t <em class="replaceable"><code>type</code></em></code>] [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] [<code class="option">-y</code>] {name}</p></div>
Francis Dupont's avatar
regen  
Francis Dupont committed
32 33
</div>
<div class="refsect1" lang="en">
Tinderbox User's avatar
Tinderbox User committed
34
<a name="id2543504"></a><h2>DESCRIPTION</h2>
Francis Dupont's avatar
regen  
Francis Dupont committed
35 36 37 38 39
<p><span><strong class="command">dnssec-keyfromlabel</strong></span>
      gets keys with the given label from a crypto hardware and builds
      key files for DNSSEC (Secure DNS), as defined in RFC 2535
      and RFC 4034.  
    </p>
Automatic Updater's avatar
regen  
Automatic Updater committed
40 41 42 43 44
<p>
      The <code class="option">name</code> of the key is specified on the command
      line.  This must match the name of the zone for which the key is
      being generated.
    </p>
Francis Dupont's avatar
regen  
Francis Dupont committed
45 46
</div>
<div class="refsect1" lang="en">
Tinderbox User's avatar
Tinderbox User committed
47
<a name="id2543522"></a><h2>OPTIONS</h2>
Francis Dupont's avatar
regen  
Francis Dupont committed
48 49 50 51 52
<div class="variablelist"><dl>
<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
<dd>
<p>
	    Selects the cryptographic algorithm.  The value of
Automatic Updater's avatar
regen  
Automatic Updater committed
53
            <code class="option">algorithm</code> must be one of RSAMD5, RSASHA1,
54 55
	    DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512, ECCGOST,
	    ECDSAP256SHA256 or ECDSAP384SHA384.
Automatic Updater's avatar
regen  
Automatic Updater committed
56
	    These values are case insensitive.
Francis Dupont's avatar
regen  
Francis Dupont committed
57
	  </p>
Automatic Updater's avatar
regen  
Automatic Updater committed
58 59 60
<p>
            If no algorithm is specified, then RSASHA1 will be used by
            default, unless the <code class="option">-3</code> option is specified,
Automatic Updater's avatar
regen  
Automatic Updater committed
61 62 63
            in which case NSEC3RSASHA1 will be used instead.  (If
            <code class="option">-3</code> is used and an algorithm is specified,
            that algorithm will be checked for compatibility with NSEC3.)
Automatic Updater's avatar
regen  
Automatic Updater committed
64
          </p>
Francis Dupont's avatar
regen  
Francis Dupont committed
65 66 67 68 69 70 71 72
<p>
            Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
            algorithm, and DSA is recommended.
          </p>
<p>
            Note 2: DH automatically sets the -k flag.
          </p>
</dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
73 74 75 76 77 78 79
<dt><span class="term">-3</span></dt>
<dd><p>
	    Use an NSEC3-capable algorithm to generate a DNSSEC key.
            If this option is used and no algorithm is explicitly
            set on the command line, NSEC3RSASHA1 will be used by
            default.
          </p></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
80 81 82
<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt>
<dd><p>
            Specifies the name of the crypto hardware (OpenSSL engine).
Automatic Updater's avatar
regen  
Automatic Updater committed
83
            When compiled with PKCS#11 support it defaults to "pkcs11".
Automatic Updater's avatar
regen  
Automatic Updater committed
84
          </p></dd>
Francis Dupont's avatar
regen  
Francis Dupont committed
85 86
<dt><span class="term">-l <em class="replaceable"><code>label</code></em></span></dt>
<dd><p>
Automatic Updater's avatar
regen  
Automatic Updater committed
87 88 89
            Specifies the label of the key pair in the crypto hardware.
            The label may be preceded by an optional OpenSSL engine name,
            separated by a colon, as in "pkcs11:keylabel".
Francis Dupont's avatar
regen  
Francis Dupont committed
90 91 92 93 94 95 96 97
          </p></dd>
<dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt>
<dd><p>
            Specifies the owner type of the key.  The value of
            <code class="option">nametype</code> 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).
Automatic Updater's avatar
regen  
Automatic Updater committed
98 99 100 101 102 103 104 105 106 107 108
            These values are case insensitive.
          </p></dd>
<dt><span class="term">-C</span></dt>
<dd><p>
	    Compatibility mode:  generates an old-style key, without
	    any metadata.  By default, <span><strong class="command">dnssec-keyfromlabel</strong></span>
	    will include the key's creation date in the metadata stored
	    with the private key, and other dates may be set there as well
	    (publication date, activation date, etc).  Keys that include
	    this data may be incompatible with older versions of BIND; the
	    <code class="option">-C</code> option suppresses them.
Francis Dupont's avatar
regen  
Francis Dupont committed
109 110 111 112 113 114 115 116 117
          </p></dd>
<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
<dd><p>
            Indicates that the DNS record containing the key should have
            the specified class.  If not specified, class IN is used.
          </p></dd>
<dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt>
<dd><p>
            Set the specified flag in the flag field of the KEY/DNSKEY record.
Automatic Updater's avatar
regen  
Automatic Updater committed
118
            The only recognized flags are KSK (Key Signing Key) and REVOKE.
Francis Dupont's avatar
regen  
Francis Dupont committed
119
          </p></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
120 121 122 123 124
<dt><span class="term">-G</span></dt>
<dd><p>
            Generate a key, but do not publish it or sign with it.  This
            option is incompatible with -P and -A.
          </p></dd>
Francis Dupont's avatar
regen  
Francis Dupont committed
125 126 127
<dt><span class="term">-h</span></dt>
<dd><p>
            Prints a short summary of the options and arguments to
Automatic Updater's avatar
regen  
Automatic Updater committed
128
            <span><strong class="command">dnssec-keyfromlabel</strong></span>.
Francis Dupont's avatar
regen  
Francis Dupont committed
129
          </p></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
130 131 132 133
<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
<dd><p>
            Sets the directory in which the key files are to be written.
          </p></dd>
Francis Dupont's avatar
regen  
Francis Dupont committed
134 135 136 137
<dt><span class="term">-k</span></dt>
<dd><p>
            Generate KEY records rather than DNSKEY records.
          </p></dd>
Automatic Updater's avatar
Automatic Updater committed
138 139 140 141 142 143 144 145 146
<dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt>
<dd><p>
            Sets the default TTL to use for this key when it is converted
            into a DNSKEY RR.  If the key is imported into a zone,
            this is the TTL that will be used for it, unless there was
            already a DNSKEY RRset in place, in which case the existing TTL
            would take precedence.  Setting the default TTL to
            <code class="literal">0</code> or <code class="literal">none</code> removes it.
          </p></dd>
Francis Dupont's avatar
regen  
Francis Dupont committed
147 148
<dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt>
<dd><p>
Automatic Updater's avatar
regen  
Automatic Updater committed
149
            Sets the protocol value for the key.  The protocol
Francis Dupont's avatar
regen  
Francis Dupont committed
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
            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.
          </p></dd>
<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt>
<dd><p>
            Indicates the use of the key.  <code class="option">type</code> 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.
          </p></dd>
<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
<dd><p>
            Sets the debugging level.
          </p></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
165 166 167 168 169 170 171 172
<dt><span class="term">-y</span></dt>
<dd><p>
            Allows DNSSEC key files to be generated even if the key ID
	    would collide with that of an existing key, in the event of
	    either key being revoked.  (This is only safe to use if you
            are sure you won't be using RFC 5011 trust anchor maintenance
            with either of the keys involved.)
          </p></dd>
Francis Dupont's avatar
regen  
Francis Dupont committed
173 174 175
</dl></div>
</div>
<div class="refsect1" lang="en">
Tinderbox User's avatar
Tinderbox User committed
176
<a name="id2543977"></a><h2>TIMING OPTIONS</h2>
Automatic Updater's avatar
regen  
Automatic Updater committed
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
<p>
      Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
      If the argument begins with a '+' or '-', it is interpreted as
      an offset from the present time.  For convenience, if such an offset
      is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
      then the offset is computed in years (defined as 365 24-hour days,
      ignoring leap years), months (defined as 30 24-hour days), weeks,
      days, hours, or minutes, respectively.  Without a suffix, the offset
      is computed in seconds.
    </p>
<div class="variablelist"><dl>
<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which a key is to be published to the zone.
            After that date, the key will be included in the zone but will
Automatic Updater's avatar
regen  
Automatic Updater committed
192 193
            not be used to sign it.  If not set, and if the -G option has
            not been used, the default is "now".
Automatic Updater's avatar
regen  
Automatic Updater committed
194 195 196 197
          </p></dd>
<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which the key is to be activated.  After that
Automatic Updater's avatar
regen  
Automatic Updater committed
198
            date, the key will be included in the zone and used to sign
Automatic Updater's avatar
regen  
Automatic Updater committed
199 200
            it.  If not set, and if the -G option has not been used, the
            default is "now".
Automatic Updater's avatar
regen  
Automatic Updater committed
201 202 203 204 205 206 207
          </p></dd>
<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which the key is to be revoked.  After that
            date, the key will be flagged as revoked.  It will be included
            in the zone and will be used to sign it.
          </p></dd>
Automatic Updater's avatar
Automatic Updater committed
208
<dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt>
Automatic Updater's avatar
regen  
Automatic Updater committed
209
<dd><p>
Automatic Updater's avatar
regen  
Automatic Updater committed
210 211 212
            Sets the date on which the key is to be retired.  After that
            date, the key will still be included in the zone, but it
            will not be used to sign it.
Automatic Updater's avatar
regen  
Automatic Updater committed
213 214 215 216
          </p></dd>
<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt>
<dd><p>
            Sets the date on which the key is to be deleted.  After that
Automatic Updater's avatar
regen  
Automatic Updater committed
217 218
            date, the key will no longer be included in the zone.  (It
            may remain in the key repository, however.)
Automatic Updater's avatar
regen  
Automatic Updater committed
219 220 221 222
          </p></dd>
</dl></div>
</div>
<div class="refsect1" lang="en">
Tinderbox User's avatar
Tinderbox User committed
223
<a name="id2543051"></a><h2>GENERATED KEY FILES</h2>
Francis Dupont's avatar
regen  
Francis Dupont committed
224 225 226 227 228 229 230 231 232 233 234
<p>
      When <span><strong class="command">dnssec-keyfromlabel</strong></span> completes
      successfully,
      it prints a string of the form <code class="filename">Knnnn.+aaa+iiiii</code>
      to the standard output.  This is an identification string for
      the key files it has generated.
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="filename">nnnn</code> is the key name.
        </p></li>
<li><p><code class="filename">aaa</code> is the numeric representation
Automatic Updater's avatar
regen  
Automatic Updater committed
235
          of the algorithm.
Francis Dupont's avatar
regen  
Francis Dupont committed
236 237 238 239 240 241 242 243 244 245
        </p></li>
<li><p><code class="filename">iiiii</code> is the key identifier (or
          footprint).
        </p></li>
</ul></div>
<p><span><strong class="command">dnssec-keyfromlabel</strong></span> 
      creates two files, with names based
      on the printed string.  <code class="filename">Knnnn.+aaa+iiiii.key</code>
      contains the public key, and
      <code class="filename">Knnnn.+aaa+iiiii.private</code> contains the
Automatic Updater's avatar
regen  
Automatic Updater committed
246
      private key.
Francis Dupont's avatar
regen  
Francis Dupont committed
247 248 249 250 251 252 253 254
    </p>
<p>
      The <code class="filename">.key</code> file contains a DNS KEY record
      that
      can be inserted into a zone file (directly or with a $INCLUDE
      statement).
    </p>
<p>
Automatic Updater's avatar
regen  
Automatic Updater committed
255 256
      The <code class="filename">.private</code> file contains
      algorithm-specific
Francis Dupont's avatar
regen  
Francis Dupont committed
257 258 259 260 261
      fields.  For obvious security reasons, this file does not have
      general read permission.
    </p>
</div>
<div class="refsect1" lang="en">
Tinderbox User's avatar
Tinderbox User committed
262
<a name="id2543124"></a><h2>SEE ALSO</h2>
Francis Dupont's avatar
regen  
Francis Dupont committed
263 264 265
<p><span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>,
      <span class="citerefentry"><span class="refentrytitle">dnssec-signzone</span>(8)</span>,
      <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
Automatic Updater's avatar
regen  
Automatic Updater committed
266
      <em class="citetitle">RFC 4034</em>.
Francis Dupont's avatar
regen  
Francis Dupont committed
267 268 269
    </p>
</div>
<div class="refsect1" lang="en">
Tinderbox User's avatar
Tinderbox User committed
270
<a name="id2543157"></a><h2>AUTHOR</h2>
Francis Dupont's avatar
regen  
Francis Dupont committed
271 272 273 274 275
<p><span class="corpauthor">Internet Systems Consortium</span>
    </p>
</div>
</div></body>
</html>