dnssec-keygen.docbook revision 2ca556300b09a94f0937b303386d29b95ef057dd
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2001 Internet Software Consortium.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - Permission to use, copy, modify, and distribute this software for any
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - purpose with or without fee is hereby granted, provided that the above
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- $Id: dnssec-keygen.docbook,v 1.4 2002/01/21 10:13:20 bwelling Exp $ -->
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refentryinfo>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refentrytitle><application>dnssec-keygen</application></refentrytitle>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refname><application>dnssec-keygen</application></refname>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refpurpose>DNSSEC key generation tool</refpurpose>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </refnamediv>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refsynopsisdiv>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <cmdsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <arg choice="req">-a <replaceable class="parameter">algorithm</replaceable></arg>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <arg choice="req">-b <replaceable class="parameter">keysize</replaceable></arg>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <arg choice="req">-n <replaceable class="parameter">nametype</replaceable></arg>
4b3f3cc67135e676a9b3b688685fb59e3494b0e6Mark Andrews <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
3398334b3acda24b086957286288ca9852662b12Automatic Updater <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
0e27506ce3135f9bd49e12564ad0e15256135118Automatic Updater <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
3b398443f0dca316ba7a6e057ba2d1b8ab4ddf70Tinderbox User <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
43b94483957d3168796a816ed86cf097518817dcTinderbox User <arg><option>-s <replaceable class="parameter">strength</replaceable></option></arg>
6ea2385360e9e2167e65f9286447da9eea189457Tinderbox User <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </cmdsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews <command>dnssec-keygen</command> generates keys for DNSSEC
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (Secure DNS), as defined in RFC 2535. It can also generate
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein keys for use with TSIG (Transaction Signatures), as
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein defined in RFC 2845.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <variablelist>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <varlistentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <term>-a <replaceable class="parameter">algorithm</replaceable></term>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Selects the cryptographic algorithm. The value of
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <option>algorithm</option> must be one of RSAMD5 or RSA,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt DSA, DH (Diffie Hellman), or HMAC-MD5. These values
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt are case insensitive.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Note that for DNSSEC, DSA is a mandatory to implement algorithm,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt and RSA is recommended. For TSIG, HMAC-MD5 is mandatory.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </varlistentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <varlistentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <term>-b <replaceable class="parameter">keysize</replaceable></term>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Specifies the number of bits in the key. The choice of key
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt size depends on the algorithm used. RSA keys must be between
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt 512 and 2048 bits. Diffie Hellman keys must be between
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt 128 and 4096 bits. DSA keys must be between 512 and 1024
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt bits and an exact multiple of 64. HMAC-MD5 keys must be
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt between 1 and 512 bits.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </varlistentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <varlistentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <term>-n <replaceable class="parameter">nametype</replaceable></term>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Specifies the owner type of the key. The value of
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <option>nametype</option> must either be ZONE (for a DNSSEC
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington zone key), HOST or ENTITY (for a key associated with a host),
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington or USER (for a key associated with a user). These values are
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington case insensitive.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term>-c <replaceable class="parameter">class</replaceable></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Indicates that the DNS record containing the key should have
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington the specified class. If not specified, class IN is used.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If generating an RSA key, use a large exponent.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term>-g <replaceable class="parameter">generator</replaceable></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If generating a Diffie Hellman key, use this generator.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Allowed values are 2 and 5. If no generator
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is specified, a known prime from RFC 2539 will be used
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if possible; otherwise the default is 2.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <varlistentry>
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt Prints a short summary of the options and arguments to
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt </varlistentry>
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <varlistentry>
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <term>-p <replaceable class="parameter">protocol</replaceable></term>
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Sets the protocol value for the generated key. The protocol
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is a number between 0 and 255. The default is 3 (DNSSEC).
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Other possible values for this argument are listed in
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt RFC 2535 and its successors.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
b0c15bd9792112fb47f6d956e580e4369e92f4e7Mark Andrews <varlistentry>
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews <term>-r <replaceable class="parameter">randomdev</replaceable></term>
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews Specifies the source of randomness. If the operating
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews system does not provide a <filename>/dev/random</filename>
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews or equivalent device, the default source of randomness
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews is keyboard input. <filename>randomdev</filename> specifies
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews the name of a character device or file containing random
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews data to be used instead of the default. The special value
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews <filename>keyboard</filename> indicates that keyboard
6844e3f010440a9f3eb200b3c2123a19e58a64dcEvan Hunt input should be used.
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews </varlistentry>
eff7f78bc65f30efd87a398e66084ddab72799d3Mark Andrews <varlistentry>
8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont <term>-s <replaceable class="parameter">strength</replaceable></term>
8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont Specifies the strength value of the key. The strength is
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Hunt a number between 0 and 15, and currently has no defined
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Hunt purpose in DNSSEC.
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Hunt </varlistentry>
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Hunt <varlistentry>
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Hunt <term>-t <replaceable class="parameter">type</replaceable></term>
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Hunt Indicates the use of the key. <option>type</option> must be
8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont is AUTHCONF. AUTH refers to the ability to authenticate
8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont data, and CONF the ability to encrypt data.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <term>-v <replaceable class="parameter">level</replaceable></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Sets the debugging level.
50105afc551903541608b11851d73278b23579a3Mark Andrews </varlistentry>
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein When <command>dnssec-keygen</command> completes successfully,
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington to the standard output. This is an identification string for
bf7f253e306d0ced8ae24d7a0598773950da11f4Mark Andrews the key it has generated. These strings can be used as arguments
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <itemizedlist>
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <filename>aaa</filename> is the numeric representation of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <filename>iiiii</filename> is the key identifier (or footprint).
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt </itemizedlist>
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt <command>dnssec-keygen</command> creates two file, with names based
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt contains the public key, and
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt <filename>Knnnn.+aaa+iiiii.private</filename> contains the private
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt The <filename>.key</filename> file contains a DNS KEY record that
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt can be inserted into a zone file (directly or with a $INCLUDE
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt The <filename>.private</filename> file contains algorithm specific
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt fields. For obvious security reasons, this file does not have
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt general read permission.
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt Both <filename>.key</filename> and <filename>.private</filename>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington files are generated for symmetric encryption algorithm such as
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington HMAC-MD5, even though the public and private key are equivalent.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein To generate a 768-bit DSA key for the domain
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <userinput>example.com</userinput>, the following command would be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington The command would print a string of the form:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein In this example, <command>dnssec-keygen</command> creates
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the files <filename>Kexample.com.+003+26160.key</filename> and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <filename>Kexample.com.+003+26160.private</filename>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <citerefentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refentrytitle>dnssec-makekeyset</refentrytitle>
61271cdee65f3313e98f382b07e6674861d9020aEvan Hunt </citerefentry>,
61271cdee65f3313e98f382b07e6674861d9020aEvan Hunt <citerefentry>
61271cdee65f3313e98f382b07e6674861d9020aEvan Hunt </citerefentry>,
61271cdee65f3313e98f382b07e6674861d9020aEvan Hunt <citerefentry>
61271cdee65f3313e98f382b07e6674861d9020aEvan Hunt </citerefentry>,
61271cdee65f3313e98f382b07e6674861d9020aEvan Hunt <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
61271cdee65f3313e98f382b07e6674861d9020aEvan Hunt <corpauthor>Internet Software Consortium</corpauthor>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - Local variables:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - mode: sgml