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