dnssec-keygen.docbook revision 2ca556300b09a94f0937b303386d29b95ef057dd
689023771c563d8660e45d439a207e06e96de28fMark Andrews<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Copyright (C) 2001 Internet Software Consortium.
689023771c563d8660e45d439a207e06e96de28fMark Andrews - Permission to use, copy, modify, and distribute this software for any
689023771c563d8660e45d439a207e06e96de28fMark 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.
689023771c563d8660e45d439a207e06e96de28fMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
689023771c563d8660e45d439a207e06e96de28fMark Andrews - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
689023771c563d8660e45d439a207e06e96de28fMark Andrews - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
689023771c563d8660e45d439a207e06e96de28fMark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
689023771c563d8660e45d439a207e06e96de28fMark Andrews - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
689023771c563d8660e45d439a207e06e96de28fMark Andrews - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
00124ad0406365d39f4b2d1011ef6a76706e9df0Mark Andrews - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!-- $Id: dnssec-keygen.docbook,v 1.4 2002/01/21 10:13:20 bwelling Exp $ -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentryinfo>
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews </refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentrytitle><application>dnssec-keygen</application></refentrytitle>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refnamediv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refname><application>dnssec-keygen</application></refname>
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews <refpurpose>DNSSEC key generation tool</refpurpose>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refnamediv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refsynopsisdiv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <cmdsynopsis>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="req">-a <replaceable class="parameter">algorithm</replaceable></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="req">-b <replaceable class="parameter">keysize</replaceable></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="req">-n <replaceable class="parameter">nametype</replaceable></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg><option>-g <replaceable class="parameter">generator</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <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>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews </cmdsynopsis>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refsynopsisdiv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <command>dnssec-keygen</command> generates keys for DNSSEC
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews (Secure DNS), as defined in RFC 2535. It can also generate
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein keys for use with TSIG (Transaction Signatures), as
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein defined in RFC 2845.
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews <variablelist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-a <replaceable class="parameter">algorithm</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Selects the cryptographic algorithm. The value of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <option>algorithm</option> must be one of RSAMD5 or RSA,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein DSA, DH (Diffie Hellman), or HMAC-MD5. These values
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein are case insensitive.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 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>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-b <replaceable class="parameter">keysize</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies the number of bits in the key. The choice of key
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein size depends on the algorithm used. RSA keys must be between
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 512 and 2048 bits. Diffie Hellman keys must be between
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 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
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein between 1 and 512 bits.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-n <replaceable class="parameter">nametype</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies the owner type of the key. The value of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <option>nametype</option> must either be ZONE (for a DNSSEC
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein zone key), HOST or ENTITY (for a key associated with a host),
00124ad0406365d39f4b2d1011ef6a76706e9df0Mark Andrews or USER (for a key associated with a user). These values are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein case insensitive.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-c <replaceable class="parameter">class</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Indicates that the DNS record containing the key should have
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the specified class. If not specified, class IN is used.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If generating an RSA key, use a large exponent.
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.
00124ad0406365d39f4b2d1011ef6a76706e9df0Mark Andrews 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.
4f6469885c3d66367e3f8fb94e1f3c66115990b0Mark Andrews </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Prints a short summary of the options and arguments to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <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).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 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>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies the source of randomness. If the operating
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein system does not provide a <filename>/dev/random</filename>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein or equivalent device, the default source of randomness
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 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
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <filename>keyboard</filename> indicates that keyboard
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein input should be used.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-s <replaceable class="parameter">strength</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Specifies the strength value of the key. The strength is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein a number between 0 and 15, and currently has no defined
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein purpose in DNSSEC.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </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
689023771c563d8660e45d439a207e06e96de28fMark Andrews 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,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 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
689023771c563d8660e45d439a207e06e96de28fMark Andrews <itemizedlist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <filename>aaa</filename> is the numeric representation of the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <filename>iiiii</filename> is the key identifier (or footprint).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </itemizedlist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <command>dnssec-keygen</command> creates two file, with names based
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein on the printed string. <filename>Knnnn.+aaa+iiiii.key</filename>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein contains the public key, and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <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
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein general read permission.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Both <filename>.key</filename> and <filename>.private</filename>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein files are generated for symmetric encryption algorithm such as
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein HMAC-MD5, even though the public and private key are equivalent.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein To generate a 768-bit DSA key for the domain
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <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:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein In this example, <command>dnssec-keygen</command> creates
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the files <filename>Kexample.com.+003+26160.key</filename> and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <filename>Kexample.com.+003+26160.private</filename>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <citerefentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentrytitle>dnssec-makekeyset</refentrytitle>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </citerefentry>,
00124ad0406365d39f4b2d1011ef6a76706e9df0Mark Andrews <citerefentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </citerefentry>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <citerefentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </citerefentry>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
689023771c563d8660e45d439a207e06e96de28fMark Andrews <corpauthor>Internet Software Consortium</corpauthor>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Local variables:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - mode: sgml