dnssec-keyfromlabel.html revision 0e9e255d1643375056aa9ed7fe2a279713ffae78
00cf03a1ca1624dac1fecc85f43fc34f8806aff9Luke Smith - Copyright (C) 2008-2010 Internet Systems Consortium, Inc. ("ISC")
00cf03a1ca1624dac1fecc85f43fc34f8806aff9Luke Smith - Permission to use, copy, modify, and/or distribute this software for any
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai - purpose with or without fee is hereby granted, provided that the above
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai - copyright notice and this permission notice appear in all copies.
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00cf03a1ca1624dac1fecc85f43fc34f8806aff9Luke Smith - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00cf03a1ca1624dac1fecc85f43fc34f8806aff9Luke Smith - PERFORMANCE OF THIS SOFTWARE.
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai<!-- $Id: dnssec-keyfromlabel.html,v 1.17 2010/12/24 01:14:19 tbox Exp $ -->
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai<a name="man.dnssec-keyfromlabel"></a><div class="titlepage"></div>
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai<p><span class="application">dnssec-keyfromlabel</span> — DNSSEC key generation tool</p>
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai<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">-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>
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai<p><span><strong class="command">dnssec-keyfromlabel</strong></span>
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai gets keys with the given label from a crypto hardware and builds
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai key files for DNSSEC (Secure DNS), as defined in RFC 2535
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai and RFC 4034.
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai The <code class="option">name</code> of the key is specified on the command
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai line. This must match the name of the zone for which the key is
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai being generated.
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai Selects the cryptographic algorithm. The value of
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai <code class="option">algorithm</code> must be one of RSAMD5, RSASHA1,
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai DSA, NSEC3RSASHA1, NSEC3DSA, RSASHA256, RSASHA512 or ECCGOST.
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai These values are case insensitive.
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai If no algorithm is specified, then RSASHA1 will be used by
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai default, unless the <code class="option">-3</code> option is specified,
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai in which case NSEC3RSASHA1 will be used instead. (If
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai <code class="option">-3</code> is used and an algorithm is specified,
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai that algorithm will be checked for compatibility with NSEC3.)
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai algorithm, and DSA is recommended.
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai Note 2: DH automatically sets the -k flag.
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai Use an NSEC3-capable algorithm to generate a DNSSEC key.
00cf03a1ca1624dac1fecc85f43fc34f8806aff9Luke Smith If this option is used and no algorithm is explicitly
00cf03a1ca1624dac1fecc85f43fc34f8806aff9Luke Smith set on the command line, NSEC3RSASHA1 will be used by
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt>
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai Specifies the name of the crypto hardware (OpenSSL engine).
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai When compiled with PKCS#11 support it defaults to "pkcs11".
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai<dt><span class="term">-l <em class="replaceable"><code>label</code></em></span></dt>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Specifies the label of the key pair in the crypto hardware.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai The label may be preceded by an optional OpenSSL engine name,
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai separated by a colon, as in "pkcs11:keylabel".
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<dt><span class="term">-n <em class="replaceable"><code>nametype</code></em></span></dt>
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai Specifies the owner type of the key. The value of
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai <code class="option">nametype</code> must either be ZONE (for a DNSSEC
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai a host (KEY)),
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai These values are case insensitive.
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai Compatibility mode: generates an old-style key, without
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai any metadata. By default, <span><strong class="command">dnssec-keyfromlabel</strong></span>
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai will include the key's creation date in the metadata stored
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai with the private key, and other dates may be set there as well
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai (publication date, activation date, etc). Keys that include
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai this data may be incompatible with older versions of BIND; the
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai <code class="option">-C</code> option suppresses them.
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai Indicates that the DNS record containing the key should have
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai the specified class. If not specified, class IN is used.
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai<dt><span class="term">-f <em class="replaceable"><code>flag</code></em></span></dt>
2cde0d56e1a4bc15add8f9cdcab3e87ff5a5b733Satyen Desai Set the specified flag in the flag field of the KEY/DNSKEY record.
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai The only recognized flags are KSK (Key Signing Key) and REVOKE.
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai Generate a key, but do not publish it or sign with it. This
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai option is incompatible with -P and -A.
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai Prints a short summary of the options and arguments to
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai <span><strong class="command">dnssec-keyfromlabel</strong></span>.
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai Sets the directory in which the key files are to be written.
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai Generate KEY records rather than DNSKEY records.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<dt><span class="term">-p <em class="replaceable"><code>protocol</code></em></span></dt>
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai Sets the protocol value for the key. The protocol
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai is a number between 0 and 255. The default is 3 (DNSSEC).
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Other possible values for this argument are listed in
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai RFC 2535 and its successors.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<dt><span class="term">-t <em class="replaceable"><code>type</code></em></span></dt>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Indicates the use of the key. <code class="option">type</code> must be
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai is AUTHCONF. AUTH refers to the ability to authenticate
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai data, and CONF the ability to encrypt data.
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Sets the debugging level.
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai Allows DNSSEC key files to be generated even if the key ID
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai would collide with that of an existing key, in the event of
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai either key being revoked. (This is only safe to use if you
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai are sure you won't be using RFC 5011 trust anchor maintenance
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai with either of the keys involved.)
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai If the argument begins with a '+' or '-', it is interpreted as
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai an offset from the present time. For convenience, if such an offset
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai then the offset is computed in years (defined as 365 24-hour days,
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai ignoring leap years), months (defined as 30 24-hour days), weeks,
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai days, hours, or minutes, respectively. Without a suffix, the offset
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai is computed in seconds.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Sets the date on which a key is to be published to the zone.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai After that date, the key will be included in the zone but will
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai not be used to sign it. If not set, and if the -G option has
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai not been used, the default is "now".
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Sets the date on which the key is to be activated. After that
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai date, the key will be included in the zone and used to sign
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai it. If not set, and if the -G option has not been used, the
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai default is "now".
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Sets the date on which the key is to be revoked. After that
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai date, the key will be flagged as revoked. It will be included
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai in the zone and will be used to sign it.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<dt><span class="term">-U <em class="replaceable"><code>date/offset</code></em></span></dt>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai Sets the date on which the key is to be retired. After that
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai date, the key will still be included in the zone, but it
d3c5729464159cab52ada7ff4b6c26b91bd4dcb4Satyen Desai will not be used to sign it.
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt>
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai Sets the date on which the key is to be deleted. After that
3deb14ef5289f666e316e224e72e532226c41be5Satyen Desai date, the key will no longer be included in the zone. (It
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai may remain in the key repository, however.)
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<a name="id2544039"></a><h2>GENERATED KEY FILES</h2>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai When <span><strong class="command">dnssec-keyfromlabel</strong></span> completes
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai successfully,
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai it prints a string of the form <code class="filename">Knnnn.+aaa+iiiii</code>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai to the standard output. This is an identification string for
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai the key files it has generated.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<li><p><code class="filename">nnnn</code> is the key name.
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai<li><p><code class="filename">aaa</code> is the numeric representation
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai of the algorithm.
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<li><p><code class="filename">iiiii</code> is the key identifier (or
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<p><span><strong class="command">dnssec-keyfromlabel</strong></span>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai creates two files, with names based
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai on the printed string. <code class="filename">Knnnn.+aaa+iiiii.key</code>
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai contains the public key, and
31689fe47c538a80973e2d32445b844f609fc5b8Satyen Desai <code class="filename">Knnnn.+aaa+iiiii.private</code> contains the
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai private key.
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai The <code class="filename">.key</code> file contains a DNS KEY record
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai can be inserted into a zone file (directly or with a $INCLUDE
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai The <code class="filename">.private</code> file contains
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai algorithm-specific
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai fields. For obvious security reasons, this file does not have
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai general read permission.
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai<p><span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>,
4de1c70b905d1ec094efa1406a5264e29ea112c9Satyen Desai <span class="citerefentry"><span class="refentrytitle">dnssec-signzone</span>(8)</span>,
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
d4a90de3308f343c5d935b5f9b6bcc9f5bc4d05fSatyen Desai<p><span class="corpauthor">Internet Systems Consortium</span>