dnssec-keygen.docbook revision dafcb997e390efa4423883dafd100c975c4095d6
3eb9ec750c9088869170dda63e8899b2ba462823Mark Andrews<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2001-2003 Internet Software Consortium.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Permission to use, copy, modify, and distribute this software for any
3eb9ec750c9088869170dda63e8899b2ba462823Mark Andrews - purpose with or without fee is hereby granted, provided that the above
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - copyright notice and this permission notice appear in all copies.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - PERFORMANCE OF THIS SOFTWARE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!-- $Id: dnssec-keygen.docbook,v 1.7 2004/03/05 04:57:40 marka Exp $ -->
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <refentryinfo>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </refentryinfo>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <refentrytitle><application>dnssec-keygen</application></refentrytitle>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refnamediv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refname><application>dnssec-keygen</application></refname>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refpurpose>DNSSEC key generation tool</refpurpose>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </refnamediv>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <refsynopsisdiv>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <cmdsynopsis>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="req">-a <replaceable class="parameter">algorithm</replaceable></arg>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <arg choice="req">-b <replaceable class="parameter">keysize</replaceable></arg>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <arg choice="req">-n <replaceable class="parameter">nametype</replaceable></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <arg><option>-f <replaceable class="parameter">flag</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <arg><option>-p <replaceable class="parameter">protocol</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg><option>-s <replaceable class="parameter">strength</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </cmdsynopsis>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refsynopsisdiv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <command>dnssec-keygen</command> generates keys for DNSSEC
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein (Secure DNS), as defined in RFC 2535. It can also generate
680033ce4d5858bb9016cfa50944eea4ff0111e3Automatic Updater keys for use with TSIG (Transaction Signatures), as
680033ce4d5858bb9016cfa50944eea4ff0111e3Automatic Updater defined in RFC 2845.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <variablelist>
b46346eb3026ba4bebc093bc93cfe159131e541eTinderbox User <varlistentry>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <term>-a <replaceable class="parameter">algorithm</replaceable></term>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Selects the cryptographic algorithm. The value of
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <option>algorithm</option> must be one of RSAMD5 or RSA,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User DSA, DH (Diffie Hellman), or HMAC-MD5. These values
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User are case insensitive.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Note that for DNSSEC, DSA is a mandatory to implement algorithm,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and RSA is recommended. For TSIG, HMAC-MD5 is mandatory.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <term>-b <replaceable class="parameter">keysize</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies the number of bits in the key. The choice of key
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User size depends on the algorithm used. RSA keys must be between
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 512 and 2048 bits. Diffie Hellman keys must be between
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User 128 and 4096 bits. DSA keys must be between 512 and 1024
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bits and an exact multiple of 64. HMAC-MD5 keys must be
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User between 1 and 512 bits.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <term>-n <replaceable class="parameter">nametype</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies the owner type of the key. The value of
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <option>nametype</option> must either be ZONE (for a DNSSEC
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein zone key), HOST or ENTITY (for a key associated with a host),
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User or USER (for a key associated with a user). These values are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein case insensitive.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-c <replaceable class="parameter">class</replaceable></term>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Indicates that the DNS record containing the key should have
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the specified class. If not specified, class IN is used.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User If generating an RSA key, use a large exponent.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <term>-f <replaceable class="parameter">flag</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Set the specified flag in the flag field of the key record.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User The only recognized flag is KSK (Key Signing Key).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-g <replaceable class="parameter">generator</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If generating a Diffie Hellman key, use this generator.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Allowed values are 2 and 5. If no generator
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is specified, a known prime from RFC 2539 will be used
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein if possible; otherwise the default is 2.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Prints a short summary of the options and arguments to
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-p <replaceable class="parameter">protocol</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Sets the protocol value for the generated key. The protocol
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is a number between 0 and 255. The default is 3 (DNSSEC).
4f6469885c3d66367e3f8fb94e1f3c66115990b0Mark Andrews Other possible values for this argument are listed in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein RFC 2535 and its successors.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-r <replaceable class="parameter">randomdev</replaceable></term>
d71e2e0c61df16ff37c9934c371a4a60c08974f7Mark Andrews Specifies the source of randomness. If the operating
d71e2e0c61df16ff37c9934c371a4a60c08974f7Mark Andrews system does not provide a <filename>/dev/random</filename>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein or equivalent device, the default source of randomness
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User is keyboard input. <filename>randomdev</filename> specifies
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the name of a character device or file containing random
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein data to be used instead of the default. The special value
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <filename>keyboard</filename> indicates that keyboard
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein input should be used.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
a1b05dea35aa30b152a47115e18bbe679d3fcf19Mark Andrews <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-s <replaceable class="parameter">strength</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies the strength value of the key. The strength is
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User a number between 0 and 15, and currently has no defined
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein purpose in DNSSEC.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-t <replaceable class="parameter">type</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Indicates the use of the key. <option>type</option> must be
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is AUTHCONF. AUTH refers to the ability to authenticate
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein data, and CONF the ability to encrypt data.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-v <replaceable class="parameter">level</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Sets the debugging level.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </variablelist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein When <command>dnssec-keygen</command> completes successfully,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User it prints a string of the form <filename>Knnnn.+aaa+iiiii</filename>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to the standard output. This is an identification string for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the key it has generated. These strings can be used as arguments
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <itemizedlist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <filename>aaa</filename> is the numeric representation of the
c986916269e0d9ca0a31efb62ff5ac06938815dbTinderbox User <filename>iiiii</filename> is the key identifier (or footprint).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </itemizedlist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <command>dnssec-keygen</command> creates two file, with names based
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein contains the public key, and
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <filename>Knnnn.+aaa+iiiii.private</filename> contains the private
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <filename>.key</filename> file contains a DNS KEY record that
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein can be inserted into a zone file (directly or with a $INCLUDE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <filename>.private</filename> file contains algorithm specific
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein fields. For obvious security reasons, this file does not have
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User general read permission.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Both <filename>.key</filename> and <filename>.private</filename>
a057e8e33baa5fa369be28a9680585200ce3ff73Mark Andrews files are generated for symmetric encryption algorithm such as
a057e8e33baa5fa369be28a9680585200ce3ff73Mark Andrews HMAC-MD5, even though the public and private key are equivalent.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User To generate a 768-bit DSA key for the domain
a057e8e33baa5fa369be28a9680585200ce3ff73Mark Andrews <userinput>example.com</userinput>, the following command would be
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <userinput>dnssec-keygen -a DSA -b 768 -n ZONE example.com</userinput>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The command would print a string of the form:
4206bb139c83dae2a8b59b7782031ccd40439aaaTinderbox User <userinput>Kexample.com.+003+26160</userinput>
4206bb139c83dae2a8b59b7782031ccd40439aaaTinderbox User In this example, <command>dnssec-keygen</command> creates
4206bb139c83dae2a8b59b7782031ccd40439aaaTinderbox User the files <filename>Kexample.com.+003+26160.key</filename> and
4206bb139c83dae2a8b59b7782031ccd40439aaaTinderbox User <filename>Kexample.com.+003+26160.private</filename>
4206bb139c83dae2a8b59b7782031ccd40439aaaTinderbox User <citerefentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <refentrytitle>dnssec-makekeyset</refentrytitle>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </citerefentry>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <citerefentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <refentrytitle>dnssec-signkey</refentrytitle>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </citerefentry>,