contrib/bind-9.2.4rc7/bin/dnssec/dnssec-keygen.8

   1 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   9 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14 .\" PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .\" $Id: dnssec-keygen.8,v 1.19.2.2 2004/06/03 05:21:09 marka Exp $
  17 .\"
  18 .TH "DNSSEC-KEYGEN" "8" "June 30, 2000" "BIND9" ""
  19 .SH NAME
  20 dnssec-keygen \- DNSSEC key generation tool
  21 .SH SYNOPSIS
  22 .sp
  23 \fBdnssec-keygen\fR \fB-a \fIalgorithm\fB\fR \fB-b \fIkeysize\fB\fR \fB-n \fInametype\fB\fR [ \fB-c \fIclass\fB\fR ]  [ \fB-e\fR ]  [ \fB-g \fIgenerator\fB\fR ]  [ \fB-h\fR ]  [ \fB-p \fIprotocol\fB\fR ]  [ \fB-r \fIrandomdev\fB\fR ]  [ \fB-s \fIstrength\fB\fR ]  [ \fB-t \fItype\fB\fR ]  [ \fB-v \fIlevel\fB\fR ]  \fBname\fR
  24 .SH "DESCRIPTION"
  25 .PP
  26 \fBdnssec-keygen\fR generates keys for DNSSEC
  27 (Secure DNS), as defined in RFC 2535. It can also generate
  28 keys for use with TSIG (Transaction Signatures), as
  29 defined in RFC 2845.
  30 .SH "OPTIONS"
  31 .TP
  32 \fB-a \fIalgorithm\fB\fR
  33 Selects the cryptographic algorithm. The value of
  34 \fBalgorithm\fR must be one of RSAMD5 or RSA,
  35 DSA, DH (Diffie Hellman), or HMAC-MD5. These values
  36 are case insensitive.
  37
  38 Note that for DNSSEC, DSA is a mandatory to implement algorithm,
  39 and RSA is recommended. For TSIG, HMAC-MD5 is mandatory.
  40 .TP
  41 \fB-b \fIkeysize\fB\fR
  42 Specifies the number of bits in the key. The choice of key
  43 size depends on the algorithm used. RSA keys must be between
  44 512 and 2048 bits. Diffie Hellman keys must be between
  45 128 and 4096 bits. DSA keys must be between 512 and 1024
  46 bits and an exact multiple of 64. HMAC-MD5 keys must be
  47 between 1 and 512 bits.
  48 .TP
  49 \fB-n \fInametype\fB\fR
  50 Specifies the owner type of the key. The value of
  51 \fBnametype\fR must either be ZONE (for a DNSSEC
  52 zone key), HOST or ENTITY (for a key associated with a host),
  53 or USER (for a key associated with a user). These values are
  54 case insensitive.
  55 .TP
  56 \fB-c \fIclass\fB\fR
  57 Indicates that the DNS record containing the key should have
  58 the specified class. If not specified, class IN is used.
  59 .TP
  60 \fB-e\fR
  61 If generating an RSA key, use a large exponent.
  62 .TP
  63 \fB-g \fIgenerator\fB\fR
  64 If generating a Diffie Hellman key, use this generator.
  65 Allowed values are 2 and 5. If no generator
  66 is specified, a known prime from RFC 2539 will be used
  67 if possible; otherwise the default is 2.
  68 .TP
  69 \fB-h\fR
  70 Prints a short summary of the options and arguments to
  71 \fBdnssec-keygen\fR.
  72 .TP
  73 \fB-p \fIprotocol\fB\fR
  74 Sets the protocol value for the generated key. The protocol
  75 is a number between 0 and 255. The default is 2 (email) for
  76 keys of type USER and 3 (DNSSEC) for all other key types.
  77 Other possible values for this argument are listed in
  78 RFC 2535 and its successors.
  79 .TP
  80 \fB-r \fIrandomdev\fB\fR
  81 Specifies the source of randomness. If the operating
  82 system does not provide a \fI/dev/random\fR
  83 or equivalent device, the default source of randomness
  84 is keyboard input. \fIrandomdev\fR specifies
  85 the name of a character device or file containing random
  86 data to be used instead of the default. The special value
  87 \fIkeyboard\fR indicates that keyboard
  88 input should be used.
  89 .TP
  90 \fB-s \fIstrength\fB\fR
  91 Specifies the strength value of the key. The strength is
  92 a number between 0 and 15, and currently has no defined
  93 purpose in DNSSEC.
  94 .TP
  95 \fB-t \fItype\fB\fR
  96 Indicates the use of the key. \fBtype\fR must be
  97 one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
  98 is AUTHCONF. AUTH refers to the ability to authenticate
  99 data, and CONF the ability to encrypt data.
 100 .TP
 101 \fB-v \fIlevel\fB\fR
 102 Sets the debugging level.
 103 .SH "GENERATED KEYS"
 104 .PP
 105 When \fBdnssec-keygen\fR completes successfully,
 106 it prints a string of the form \fIKnnnn.+aaa+iiiii\fR
 107 to the standard output. This is an identification string for
 108 the key it has generated. These strings can be used as arguments
 109 to \fBdnssec-makekeyset\fR.
 110 .TP 0.2i
 111 \(bu
 112 \fInnnn\fR is the key name.
 113 .TP 0.2i
 114 \(bu
 115 \fIaaa\fR is the numeric representation of the
 116 algorithm.
 117 .TP 0.2i
 118 \(bu
 119 \fIiiiii\fR is the key identifier (or footprint).
 120 .PP
 121 \fBdnssec-keygen\fR creates two file, with names based
 122 on the printed string. \fIKnnnn.+aaa+iiiii.key\fR
 123 contains the public key, and
 124 \fIKnnnn.+aaa+iiiii.private\fR contains the private
 125 key.
 126 .PP
 127 .PP
 128 The \fI.key\fR file contains a DNS KEY record that
 129 can be inserted into a zone file (directly or with a $INCLUDE
 130 statement).
 131 .PP
 132 .PP
 133 The \fI.private\fR file contains algorithm specific
 134 fields. For obvious security reasons, this file does not have
 135 general read permission.
 136 .PP
 137 .PP
 138 Both \fI.key\fR and \fI.private\fR
 139 files are generated for symmetric encryption algorithm such as
 140 HMAC-MD5, even though the public and private key are equivalent.
 141 .PP
 142 .SH "EXAMPLE"
 143 .PP
 144 To generate a 768-bit DSA key for the domain
 145 \fBexample.com\fR, the following command would be
 146 issued:
 147 .PP
 148 \fBdnssec-keygen -a DSA -b 768 -n ZONE example.com\fR
 149 .PP
 150 The command would print a string of the form:
 151 .PP
 152 \fBKexample.com.+003+26160\fR
 153 .PP
 154 In this example, \fBdnssec-keygen\fR creates
 155 the files \fIKexample.com.+003+26160.key\fR and
 156 \fIKexample.com.+003+26160.private\fR
 157 .SH "SEE ALSO"
 158 .PP
 159 \fBdnssec-makekeyset\fR(8),
 160 \fBdnssec-signkey\fR(8),
 161 \fBdnssec-signzone\fR(8),
 162 \fIBIND 9 Administrator Reference Manual\fR,
 163 \fIRFC 2535\fR,
 164 \fIRFC 2845\fR,
 165 \fIRFC 2539\fR.
 166 .SH "AUTHOR"
 167 .PP
 168 Internet Systems Consortium