Merge from vendor branch TEXINFO:
[dragonfly.git] / 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