dnssec-keygen.docbook revision 733531b6d5c705dad87e85a2bcc557f68f902bb3
12343c067e12be071a68bbb10d1d1c4870696769Tinderbox User<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
6c2a76b3e2ccd32c35814b6e0f54da00190749d7Evan Hunt "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater [<!ENTITY mdash "—">]>
e5404e49304b1f8f13a03cc63e5341e4501735ceTinderbox User - Copyright (C) 2004, 2005, 2007, 2008 Internet Systems Consortium, Inc. ("ISC")
ba9e87b35e561bc7354ce3f4b9685b747b7be507Tinderbox User - Copyright (C) 2000-2003 Internet Software Consortium.
59663800d2ec04777dae2791dd92aa563faf94c8Evan Hunt - Permission to use, copy, modify, and/or distribute this software for any
d0036fd5ddfe3c8e24151bbb1f21bc51bf876774Tinderbox User - purpose with or without fee is hereby granted, provided that the above
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - copyright notice and this permission notice appear in all copies.
59663800d2ec04777dae2791dd92aa563faf94c8Evan Hunt - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
1ca2cf024391992fe14b2df7d3ae0f575d074452Evan Hunt - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
0726d872f6f36901ea09321df57084614e5bb6faTinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
1ca2cf024391992fe14b2df7d3ae0f575d074452Evan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - PERFORMANCE OF THIS SOFTWARE.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<!-- $Id: dnssec-keygen.docbook,v 1.22 2008/10/14 14:32:50 jreed Exp $ -->
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refentryinfo>
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrews </refentryinfo>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <refentrytitle><application>dnssec-keygen</application></refentrytitle>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <refnamediv>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <refname><application>dnssec-keygen</application></refname>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <refpurpose>DNSSEC key generation tool</refpurpose>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User </refnamediv>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews </copyright>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </copyright>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refsynopsisdiv>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <cmdsynopsis>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt <arg choice="req">-a <replaceable class="parameter">algorithm</replaceable></arg>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <arg choice="req">-b <replaceable class="parameter">keysize</replaceable></arg>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <arg choice="req">-n <replaceable class="parameter">nametype</replaceable></arg>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User <arg><option>-s <replaceable class="parameter">strength</replaceable></option></arg>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </cmdsynopsis>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </refsynopsisdiv>
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews generates keys for DNSSEC (Secure DNS), as defined in RFC 2535
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews and RFC 4034. It can also generate keys for use with
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews TSIG (Transaction Signatures), as defined in RFC 2845.
ebe53509ca55a141131c104b6d722236b606e0efTinderbox User <variablelist>
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews <varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <term>-a <replaceable class="parameter">algorithm</replaceable></term>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews Selects the cryptographic algorithm. The value of
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User <option>algorithm</option> must be one of RSAMD5 (RSA) or RSASHA1,
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt DSA, NSEC3RSASHA1, NSEC3DSA, DH (Diffie Hellman), or HMAC-MD5.
7cc0a5d21ef046bfd630c4769943d896a7d7472cTinderbox User These values are case insensitive.
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User Note 1: that for DNSSEC, RSASHA1 is a mandatory to implement
551e6d2414c4f47d58a9bb0b37f206f915a4f5acTinderbox User algorithm, and DSA is recommended. For TSIG, HMAC-MD5 is
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User Note 2: HMAC-MD5 and DH automatically set the -k flag.
51aeb0ae19596e99b029cfa933e73b76ebec480aTinderbox User </varlistentry>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User <varlistentry>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User <term>-b <replaceable class="parameter">keysize</replaceable></term>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson Specifies the number of bits in the key. The choice of key
415d630b6309922caee8469384a6fab75cf05032Mark Andrews size depends on the algorithm used. RSAMD5 / RSASHA1 keys must be
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User 512 and 2048 bits. Diffie Hellman keys must be between
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews 128 and 4096 bits. DSA keys must be between 512 and 1024
415d630b6309922caee8469384a6fab75cf05032Mark Andrews bits and an exact multiple of 64. HMAC-MD5 keys must be
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews between 1 and 512 bits.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </varlistentry>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <term>-n <replaceable class="parameter">nametype</replaceable></term>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Specifies the owner type of the key. The value of
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <option>nametype</option> must either be ZONE (for a DNSSEC
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with
415d630b6309922caee8469384a6fab75cf05032Mark Andrews a host (KEY)),
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews USER (for a key associated with a user(KEY)) or OTHER (DNSKEY).
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User These values are case insensitive. Defaults to ZONE for DNSKEY
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews <term>-c <replaceable class="parameter">class</replaceable></term>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews Indicates that the DNS record containing the key should have
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews the specified class. If not specified, class IN is used.
baeaed18341c015e9ad54ffa21973184c1bc432bMark Andrews </varlistentry>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <varlistentry>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews If generating an RSAMD5/RSASHA1 key, use a large exponent.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews </varlistentry>
33b0d10552ea5f7716385b2cedff64daa1486c50Tinderbox User <varlistentry>
b378314925e78f21853a98cec924788ce1822c6cTinderbox User <term>-f <replaceable class="parameter">flag</replaceable></term>
2b7254075b883d70852a2757210793603085a0f1Tinderbox User Set the specified flag in the flag field of the KEY/DNSKEY record.
66317da170ed35b08f5847db2d48b225826327cbTinderbox User The only recognized flag is KSK (Key Signing Key) DNSKEY.
b625bdae12277225b076a002dd4af80902529181Tinderbox User </varlistentry>
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews <varlistentry>
2b7254075b883d70852a2757210793603085a0f1Tinderbox User <term>-g <replaceable class="parameter">generator</replaceable></term>
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater If generating a Diffie Hellman key, use this generator.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews Allowed values are 2 and 5. If no generator
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User is specified, a known prime from RFC 2539 will be used
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews if possible; otherwise the default is 2.
415d630b6309922caee8469384a6fab75cf05032Mark Andrews </varlistentry>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User <varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews Prints a short summary of the options and arguments to
415d630b6309922caee8469384a6fab75cf05032Mark Andrews </varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews Generate KEY records rather than DNSKEY records.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </varlistentry>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <term>-p <replaceable class="parameter">protocol</replaceable></term>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews Sets the protocol value for the generated key. The protocol
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User is a number between 0 and 255. The default is 3 (DNSSEC).
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Other possible values for this argument are listed in
415d630b6309922caee8469384a6fab75cf05032Mark Andrews RFC 2535 and its successors.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </varlistentry>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <term>-r <replaceable class="parameter">randomdev</replaceable></term>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews Specifies the source of randomness. If the operating
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User system does not provide a <filename>/dev/random</filename>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews or equivalent device, the default source of randomness
415d630b6309922caee8469384a6fab75cf05032Mark Andrews is keyboard input. <filename>randomdev</filename>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews the name of a character device or file containing random
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews data to be used instead of the default. The special value
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User <filename>keyboard</filename> indicates that keyboard
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews input should be used.
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
0536b2e5496752fd497ad26322cbf60d7746e7acTinderbox User <term>-s <replaceable class="parameter">strength</replaceable></term>
fab54780409846f7c71f6026d665f18c77c649efTinderbox User Specifies the strength value of the key. The strength is
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews a number between 0 and 15, and currently has no defined
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox User purpose in DNSSEC.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </varlistentry>
0536b2e5496752fd497ad26322cbf60d7746e7acTinderbox User <varlistentry>
6c2a76b3e2ccd32c35814b6e0f54da00190749d7Evan Hunt <term>-t <replaceable class="parameter">type</replaceable></term>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews Indicates the use of the key. <option>type</option> must be
98240f34c38524fd6d0db5a42b9d47cd95ec0fa1Tinderbox User one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews is AUTHCONF. AUTH refers to the ability to authenticate
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews data, and CONF the ability to encrypt data.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <term>-v <replaceable class="parameter">level</replaceable></term>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews Sets the debugging level.
98240f34c38524fd6d0db5a42b9d47cd95ec0fa1Tinderbox User </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </variablelist>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews When <command>dnssec-keygen</command> completes
8ac5ddf659a81ed668579818981fc1a5f28405d1Tinderbox User successfully,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
98240f34c38524fd6d0db5a42b9d47cd95ec0fa1Tinderbox User to the standard output. This is an identification string for
1ef84760d1d9c2f4610c3f9c777267388971ae80Tinderbox User the key it has generated.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <itemizedlist>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <para><filename>nnnn</filename> is the key name.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <para><filename>aaa</filename> is the numeric representation
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <para><filename>iiiii</filename> is the key identifier (or
e5c7ef08d1bf9f8388de8174a47da78b9eeb7e5cTinderbox User </itemizedlist>
0536b2e5496752fd497ad26322cbf60d7746e7acTinderbox User creates two files, with names based
2f16d4dc2979b55340991f6d9248efdd61d8d3b6Tinderbox User on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
9775151e65bb4b39ccc4cd198a166dc354cacb09Tinderbox User contains the public key, and
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <filename>Knnnn.+aaa+iiiii.private</filename> contains the
c4d2e7c8c8fe06009165275bee0703b0ef85e19fTinderbox User The <filename>.key</filename> file contains a DNS KEY record
076e51f1ff9497ae61a99994189ed8bf5a0d3472Tinderbox User can be inserted into a zone file (directly or with a $INCLUDE
076e51f1ff9497ae61a99994189ed8bf5a0d3472Tinderbox User The <filename>.private</filename> file contains
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User algorithm-specific
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson fields. For obvious security reasons, this file does not have
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox User general read permission.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Both <filename>.key</filename> and <filename>.private</filename>
8ac5ddf659a81ed668579818981fc1a5f28405d1Tinderbox User files are generated for symmetric encryption algorithms such as
076e51f1ff9497ae61a99994189ed8bf5a0d3472Tinderbox User HMAC-MD5, even though the public and private key are equivalent.
5e145d312503505bed49bcd72d1062b82989cadaTinderbox User To generate a 768-bit DSA key for the domain
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <userinput>example.com</userinput>, the following command would be
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <para><userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews The command would print a string of the form:
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <para><userinput>Kexample.com.+003+26160</userinput>
c1e2310a3725eeed45e5e7c86750c64c5a02e993Francis Dupont In this example, <command>dnssec-keygen</command> creates
4b61b671f5de767ec1d1b8e6cf7b849bddf08e98Tinderbox User the files <filename>Kexample.com.+003+26160.key</filename>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews <filename>Kexample.com.+003+26160.private</filename>.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews </citerefentry>,
f1a2709aad7baa4161fdb6f63edf99b0150af252Evan Hunt <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <para><corpauthor>Internet Systems Consortium</corpauthor>
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater - Local variables:
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - mode: sgml