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-2012, 2014 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<refentry id="man.dnssec-keyfromlabel"> 21 <refentryinfo> 22 <date>February 27, 2014</date> 23 </refentryinfo> 24 25 <refmeta> 26 <refentrytitle><application>dnssec-keyfromlabel</application></refentrytitle> 27 <manvolnum>8</manvolnum> 28 <refmiscinfo>BIND9</refmiscinfo> 29 </refmeta> 30 31 <refnamediv> 32 <refname><application>dnssec-keyfromlabel</application></refname> 33 <refpurpose>DNSSEC key generation tool</refpurpose> 34 </refnamediv> 35 36 <docinfo> 37 <copyright> 38 <year>2008</year> 39 <year>2009</year> 40 <year>2010</year> 41 <year>2011</year> 42 <year>2012</year> 43 <year>2014</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>-i <replaceable class="parameter">interval</replaceable></option></arg> 62 <arg><option>-k</option></arg> 63 <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg> 64 <arg><option>-L <replaceable class="parameter">ttl</replaceable></option></arg> 65 <arg><option>-n <replaceable class="parameter">nametype</replaceable></option></arg> 66 <arg><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg> 67 <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg> 68 <arg><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg> 69 <arg><option>-S <replaceable class="parameter">key</replaceable></option></arg> 70 <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg> 71 <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg> 72 <arg><option>-V</option></arg> 73 <arg><option>-y</option></arg> 74 <arg choice="req">name</arg> 75 </cmdsynopsis> 76 </refsynopsisdiv> 77 78 <refsect1> 79 <title>DESCRIPTION</title> 80 <para><command>dnssec-keyfromlabel</command> 81 generates a key pair of files that referencing a key object stored 82 in a cryptographic hardware service module (HSM). The private key 83 file can be used for DNSSEC signing of zone data as if it were a 84 conventional signing key created by <command>dnssec-keygen</command>, 85 but the key material is stored within the HSM, and the actual signing 86 takes place there. 87 </para> 88 <para> 89 The <option>name</option> of the key is specified on the command 90 line. This must match the name of the zone for which the key is 91 being generated. 92 </para> 93 </refsect1> 94 95 <refsect1> 96 <title>OPTIONS</title> 97 98 <variablelist> 99 <varlistentry> 100 <term>-a <replaceable class="parameter">algorithm</replaceable></term> 101 <listitem> 102 <para> 103 Selects the cryptographic algorithm. The value of 104 <option>algorithm</option> must be one of RSAMD5, RSASHA1, 105 DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512, ECCGOST, 106 ECDSAP256SHA256 or ECDSAP384SHA384. 107 These values are case insensitive. 108 </para> 109 <para> 110 If no algorithm is specified, then RSASHA1 will be used by 111 default, unless the <option>-3</option> option is specified, 112 in which case NSEC3RSASHA1 will be used instead. (If 113 <option>-3</option> is used and an algorithm is specified, 114 that algorithm will be checked for compatibility with NSEC3.) 115 </para> 116 <para> 117 Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement 118 algorithm, and DSA is recommended. 119 </para> 120 <para> 121 Note 2: DH automatically sets the -k flag. 122 </para> 123 </listitem> 124 </varlistentry> 125 126 <varlistentry> 127 <term>-3</term> 128 <listitem> 129 <para> 130 Use an NSEC3-capable algorithm to generate a DNSSEC key. 131 If this option is used and no algorithm is explicitly 132 set on the command line, NSEC3RSASHA1 will be used by 133 default. 134 </para> 135 </listitem> 136 </varlistentry> 137 138 <varlistentry> 139 <term>-E <replaceable class="parameter">engine</replaceable></term> 140 <listitem> 141 <para> 142 Specifies the cryptographic hardware to use. 143 </para> 144 <para> 145 When BIND is built with OpenSSL PKCS#11 support, this defaults 146 to the string "pkcs11", which identifies an OpenSSL engine 147 that can drive a cryptographic accelerator or hardware service 148 module. When BIND is built with native PKCS#11 cryptography 149 (--enable-native-pkcs11), it defaults to the path of the PKCS#11 150 provider library specified via "--with-pkcs11". 151 </para> 152 </listitem> 153 </varlistentry> 154 155 <varlistentry> 156 <term>-l <replaceable class="parameter">label</replaceable></term> 157 <listitem> 158 <para> 159 Specifies the label for a key pair in the crypto hardware. 160 </para> 161 <para> 162 When <acronym>BIND</acronym> 9 is built with OpenSSL-based 163 PKCS#11 support, the label is an arbitrary string that 164 identifies a particular key. It may be preceded by an 165 optional OpenSSL engine name, followed by a colon, as in 166 "pkcs11:<replaceable>keylabel</replaceable>". 167 </para> 168 <para> 169 When <acronym>BIND</acronym> 9 is built with native PKCS#11 170 support, the label is a PKCS#11 URI string in the format 171 "pkcs11:<option>keyword</option>=<replaceable>value</replaceable><optional>;<option>keyword</option>=<replaceable>value</replaceable>;...</optional>" 172 Keywords include "token", which identifies the HSM; "object", which 173 identifies the key; and "pin-source", which identifies a file from 174 which the HSM's PIN code can be obtained. The label will be 175 stored in the on-disk "private" file. 176 </para> 177 <para> 178 If the label contains a 179 <option>pin-source</option> field, tools using the generated 180 key files will be able to use the HSM for signing and other 181 operations without any need for an operator to manually enter 182 a PIN. Note: Making the HSM's PIN accessible in this manner 183 may reduce the security advantage of using an HSM; be sure 184 this is what you want to do before making use of this feature. 185 </para> 186 </listitem> 187 </varlistentry> 188 189 <varlistentry> 190 <term>-n <replaceable class="parameter">nametype</replaceable></term> 191 <listitem> 192 <para> 193 Specifies the owner type of the key. The value of 194 <option>nametype</option> must either be ZONE (for a DNSSEC 195 zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with 196 a host (KEY)), 197 USER (for a key associated with a user(KEY)) or OTHER (DNSKEY). 198 These values are case insensitive. 199 </para> 200 </listitem> 201 </varlistentry> 202 203 <varlistentry> 204 <term>-C</term> 205 <listitem> 206 <para> 207 Compatibility mode: generates an old-style key, without 208 any metadata. By default, <command>dnssec-keyfromlabel</command> 209 will include the key's creation date in the metadata stored 210 with the private key, and other dates may be set there as well 211 (publication date, activation date, etc). Keys that include 212 this data may be incompatible with older versions of BIND; the 213 <option>-C</option> option suppresses them. 214 </para> 215 </listitem> 216 </varlistentry> 217 218 <varlistentry> 219 <term>-c <replaceable class="parameter">class</replaceable></term> 220 <listitem> 221 <para> 222 Indicates that the DNS record containing the key should have 223 the specified class. If not specified, class IN is used. 224 </para> 225 </listitem> 226 </varlistentry> 227 228 <varlistentry> 229 <term>-f <replaceable class="parameter">flag</replaceable></term> 230 <listitem> 231 <para> 232 Set the specified flag in the flag field of the KEY/DNSKEY record. 233 The only recognized flags are KSK (Key Signing Key) and REVOKE. 234 </para> 235 </listitem> 236 </varlistentry> 237 238 <varlistentry> 239 <term>-G</term> 240 <listitem> 241 <para> 242 Generate a key, but do not publish it or sign with it. This 243 option is incompatible with -P and -A. 244 </para> 245 </listitem> 246 </varlistentry> 247 248 <varlistentry> 249 <term>-h</term> 250 <listitem> 251 <para> 252 Prints a short summary of the options and arguments to 253 <command>dnssec-keyfromlabel</command>. 254 </para> 255 </listitem> 256 </varlistentry> 257 258 <varlistentry> 259 <term>-K <replaceable class="parameter">directory</replaceable></term> 260 <listitem> 261 <para> 262 Sets the directory in which the key files are to be written. 263 </para> 264 </listitem> 265 </varlistentry> 266 267 <varlistentry> 268 <term>-k</term> 269 <listitem> 270 <para> 271 Generate KEY records rather than DNSKEY records. 272 </para> 273 </listitem> 274 </varlistentry> 275 276 <varlistentry> 277 <term>-L <replaceable class="parameter">ttl</replaceable></term> 278 <listitem> 279 <para> 280 Sets the default TTL to use for this key when it is converted 281 into a DNSKEY RR. If the key is imported into a zone, 282 this is the TTL that will be used for it, unless there was 283 already a DNSKEY RRset in place, in which case the existing TTL 284 would take precedence. Setting the default TTL to 285 <literal>0</literal> or <literal>none</literal> removes it. 286 </para> 287 </listitem> 288 </varlistentry> 289 290 <varlistentry> 291 <term>-p <replaceable class="parameter">protocol</replaceable></term> 292 <listitem> 293 <para> 294 Sets the protocol value for the key. The protocol 295 is a number between 0 and 255. The default is 3 (DNSSEC). 296 Other possible values for this argument are listed in 297 RFC 2535 and its successors. 298 </para> 299 </listitem> 300 </varlistentry> 301 302 <varlistentry> 303 <term>-S <replaceable class="parameter">key</replaceable></term> 304 <listitem> 305 <para> 306 Generate a key as an explicit successor to an existing key. 307 The name, algorithm, size, and type of the key will be set 308 to match the predecessor. The activation date of the new 309 key will be set to the inactivation date of the existing 310 one. The publication date will be set to the activation 311 date minus the prepublication interval, which defaults to 312 30 days. 313 </para> 314 </listitem> 315 </varlistentry> 316 317 <varlistentry> 318 <term>-t <replaceable class="parameter">type</replaceable></term> 319 <listitem> 320 <para> 321 Indicates the use of the key. <option>type</option> must be 322 one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default 323 is AUTHCONF. AUTH refers to the ability to authenticate 324 data, and CONF the ability to encrypt data. 325 </para> 326 </listitem> 327 </varlistentry> 328 329 <varlistentry> 330 <term>-v <replaceable class="parameter">level</replaceable></term> 331 <listitem> 332 <para> 333 Sets the debugging level. 334 </para> 335 </listitem> 336 </varlistentry> 337 338 <varlistentry> 339 <term>-V</term> 340 <listitem> 341 <para> 342 Prints version information. 343 </para> 344 </listitem> 345 </varlistentry> 346 347 <varlistentry> 348 <term>-y</term> 349 <listitem> 350 <para> 351 Allows DNSSEC key files to be generated even if the key ID 352 would collide with that of an existing key, in the event of 353 either key being revoked. (This is only safe to use if you 354 are sure you won't be using RFC 5011 trust anchor maintenance 355 with either of the keys involved.) 356 </para> 357 </listitem> 358 </varlistentry> 359 360 </variablelist> 361 </refsect1> 362 363 <refsect1> 364 <title>TIMING OPTIONS</title> 365 366 <para> 367 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. 368 If the argument begins with a '+' or '-', it is interpreted as 369 an offset from the present time. For convenience, if such an offset 370 is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', 371 then the offset is computed in years (defined as 365 24-hour days, 372 ignoring leap years), months (defined as 30 24-hour days), weeks, 373 days, hours, or minutes, respectively. Without a suffix, the offset 374 is computed in seconds. To explicitly prevent a date from being 375 set, use 'none' or 'never'. 376 </para> 377 378 <variablelist> 379 <varlistentry> 380 <term>-P <replaceable class="parameter">date/offset</replaceable></term> 381 <listitem> 382 <para> 383 Sets the date on which a key is to be published to the zone. 384 After that date, the key will be included in the zone but will 385 not be used to sign it. If not set, and if the -G option has 386 not been used, the default is "now". 387 </para> 388 </listitem> 389 </varlistentry> 390 391 <varlistentry> 392 <term>-A <replaceable class="parameter">date/offset</replaceable></term> 393 <listitem> 394 <para> 395 Sets the date on which the key is to be activated. After that 396 date, the key will be included in the zone and used to sign 397 it. If not set, and if the -G option has not been used, the 398 default is "now". 399 </para> 400 </listitem> 401 </varlistentry> 402 403 <varlistentry> 404 <term>-R <replaceable class="parameter">date/offset</replaceable></term> 405 <listitem> 406 <para> 407 Sets the date on which the key is to be revoked. After that 408 date, the key will be flagged as revoked. It will be included 409 in the zone and will be used to sign it. 410 </para> 411 </listitem> 412 </varlistentry> 413 414 <varlistentry> 415 <term>-I <replaceable class="parameter">date/offset</replaceable></term> 416 <listitem> 417 <para> 418 Sets the date on which the key is to be retired. After that 419 date, the key will still be included in the zone, but it 420 will not be used to sign it. 421 </para> 422 </listitem> 423 </varlistentry> 424 425 <varlistentry> 426 <term>-D <replaceable class="parameter">date/offset</replaceable></term> 427 <listitem> 428 <para> 429 Sets the date on which the key is to be deleted. After that 430 date, the key will no longer be included in the zone. (It 431 may remain in the key repository, however.) 432 </para> 433 </listitem> 434 </varlistentry> 435 436 <varlistentry> 437 <term>-i <replaceable class="parameter">interval</replaceable></term> 438 <listitem> 439 <para> 440 Sets the prepublication interval for a key. If set, then 441 the publication and activation dates must be separated by at least 442 this much time. If the activation date is specified but the 443 publication date isn't, then the publication date will default 444 to this much time before the activation date; conversely, if 445 the publication date is specified but activation date isn't, 446 then activation will be set to this much time after publication. 447 </para> 448 <para> 449 If the key is being created as an explicit successor to another 450 key, then the default prepublication interval is 30 days; 451 otherwise it is zero. 452 </para> 453 <para> 454 As with date offsets, if the argument is followed by one of 455 the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the 456 interval is measured in years, months, weeks, days, hours, 457 or minutes, respectively. Without a suffix, the interval is 458 measured in seconds. 459 </para> 460 </listitem> 461 </varlistentry> 462 463 </variablelist> 464 </refsect1> 465 466 <refsect1> 467 <title>GENERATED KEY FILES</title> 468 <para> 469 When <command>dnssec-keyfromlabel</command> completes 470 successfully, 471 it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename> 472 to the standard output. This is an identification string for 473 the key files it has generated. 474 </para> 475 <itemizedlist> 476 <listitem> 477 <para><filename>nnnn</filename> is the key name. 478 </para> 479 </listitem> 480 <listitem> 481 <para><filename>aaa</filename> is the numeric representation 482 of the algorithm. 483 </para> 484 </listitem> 485 <listitem> 486 <para><filename>iiiii</filename> is the key identifier (or 487 footprint). 488 </para> 489 </listitem> 490 </itemizedlist> 491 <para><command>dnssec-keyfromlabel</command> 492 creates two files, with names based 493 on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename> 494 contains the public key, and 495 <filename>Knnnn.+aaa+iiiii.private</filename> contains the 496 private key. 497 </para> 498 <para> 499 The <filename>.key</filename> file contains a DNS KEY record 500 that 501 can be inserted into a zone file (directly or with a $INCLUDE 502 statement). 503 </para> 504 <para> 505 The <filename>.private</filename> file contains 506 algorithm-specific 507 fields. For obvious security reasons, this file does not have 508 general read permission. 509 </para> 510 </refsect1> 511 512 <refsect1> 513 <title>SEE ALSO</title> 514 <para><citerefentry> 515 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum> 516 </citerefentry>, 517 <citerefentry> 518 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum> 519 </citerefentry>, 520 <citetitle>BIND 9 Administrator Reference Manual</citetitle>, 521 <citetitle>RFC 4034</citetitle>, 522 <citetitle>The PKCS#11 URI Scheme (draft-pechanec-pkcs11uri-13)</citetitle>. 523 </para> 524 </refsect1> 525 526 <refsect1> 527 <title>AUTHOR</title> 528 <para><corpauthor>Internet Systems Consortium</corpauthor> 529 </para> 530 </refsect1> 531 532</refentry><!-- 533 - Local variables: 534 - mode: sgml 535 - End: 536--> 537