/contrib/bind9/bin/dnssec/dnssec-keyfromlabel.docbook
Unknown | 429 lines | 394 code | 35 blank | 0 comment | 0 complexity | 63034904a3d2d9faf86445bc211b4345 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
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 "—">]> 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-->