PageRenderTime 28ms CodeModel.GetById 14ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

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

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