Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_13_...
[ipreg/bind9.git] / bin / dnssec / dnssec-keygen.8
1 .\" Copyright (C) 2000-2005, 2007-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
2 .\"
3 .\" This Source Code Form is subject to the terms of the Mozilla Public
4 .\" License, v. 2.0. If a copy of the MPL was not distributed with this
5 .\" file, You can obtain one at http://mozilla.org/MPL/2.0/.
6 .\"
7 .hy 0
8 .ad l
9 '\" t
10 .\" Title: dnssec-keygen
11 .\" Author:
12 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
13 .\" Date: August 21, 2015
14 .\" Manual: BIND9
15 .\" Source: ISC
16 .\" Language: English
17 .\"
18 .TH "DNSSEC\-KEYGEN" "8" "August 21, 2015" "ISC" "BIND9"
19 .\" -----------------------------------------------------------------
20 .\" * Define some portability stuff
21 .\" -----------------------------------------------------------------
22 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23 .\" http://bugs.debian.org/507673
24 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
25 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 .ie \n(.g .ds Aq \(aq
27 .el .ds Aq '
28 .\" -----------------------------------------------------------------
29 .\" * set default formatting
30 .\" -----------------------------------------------------------------
31 .\" disable hyphenation
32 .nh
33 .\" disable justification (adjust text to left margin only)
34 .ad l
35 .\" -----------------------------------------------------------------
36 .\" * MAIN CONTENT STARTS HERE *
37 .\" -----------------------------------------------------------------
38 .SH "NAME"
39 dnssec-keygen \- DNSSEC key generation tool
40 .SH "SYNOPSIS"
41 .HP \w'\fBdnssec\-keygen\fR\ 'u
42 \fBdnssec\-keygen\fR [\fB\-a\ \fR\fB\fIalgorithm\fR\fR] [\fB\-b\ \fR\fB\fIkeysize\fR\fR] [\fB\-n\ \fR\fB\fInametype\fR\fR] [\fB\-3\fR] [\fB\-A\ \fR\fB\fIdate/offset\fR\fR] [\fB\-C\fR] [\fB\-c\ \fR\fB\fIclass\fR\fR] [\fB\-D\ \fR\fB\fIdate/offset\fR\fR] [\fB\-D\ sync\ \fR\fB\fIdate/offset\fR\fR] [\fB\-E\ \fR\fB\fIengine\fR\fR] [\fB\-f\ \fR\fB\fIflag\fR\fR] [\fB\-G\fR] [\fB\-g\ \fR\fB\fIgenerator\fR\fR] [\fB\-h\fR] [\fB\-I\ \fR\fB\fIdate/offset\fR\fR] [\fB\-i\ \fR\fB\fIinterval\fR\fR] [\fB\-K\ \fR\fB\fIdirectory\fR\fR] [\fB\-k\fR] [\fB\-L\ \fR\fB\fIttl\fR\fR] [\fB\-P\ \fR\fB\fIdate/offset\fR\fR] [\fB\-P\ sync\ \fR\fB\fIdate/offset\fR\fR] [\fB\-p\ \fR\fB\fIprotocol\fR\fR] [\fB\-q\fR] [\fB\-R\ \fR\fB\fIdate/offset\fR\fR] [\fB\-S\ \fR\fB\fIkey\fR\fR] [\fB\-s\ \fR\fB\fIstrength\fR\fR] [\fB\-t\ \fR\fB\fItype\fR\fR] [\fB\-V\fR] [\fB\-v\ \fR\fB\fIlevel\fR\fR] [\fB\-z\fR] {name}
43 .SH "DESCRIPTION"
44 .PP
45 \fBdnssec\-keygen\fR
46 generates keys for DNSSEC (Secure DNS), as defined in RFC 2535 and RFC 4034\&. It can also generate keys for use with TSIG (Transaction Signatures) as defined in RFC 2845, or TKEY (Transaction Key) as defined in RFC 2930\&.
47 .PP
48 The
49 \fBname\fR
50 of the key is specified on the command line\&. For DNSSEC keys, this must match the name of the zone for which the key is being generated\&.
51 .PP
52 The
53 \fBdnssec\-keymgr\fR
54 command acts as a wrapper around
55 \fBdnssec\-keygen\fR, generating and updating keys as needed to enforce defined security policies such as key rollover scheduling\&. Using
56 \fBdnssec\-keymgr\fR
57 may be preferable to direct use of
58 \fBdnssec\-keygen\fR\&.
59 .SH "OPTIONS"
60 .PP
61 \-a \fIalgorithm\fR
62 .RS 4
63 Selects the cryptographic algorithm\&. For DNSSEC keys, the value of
64 \fBalgorithm\fR
65 must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448\&. For TKEY, the value must be DH (Diffie Hellman); specifying his value will automatically set the
66 \fB\-T KEY\fR
67 option as well\&.
68 .sp
69 These values are case insensitive\&. In some cases, abbreviations are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for ECDSAP384SHA384\&. If RSASHA1 is specified along with the
70 \fB\-3\fR
71 option, then NSEC3RSASHA1 will be used instead\&.
72 .sp
73 This parameter
74 \fImust\fR
75 be specified except when using the
76 \fB\-S\fR
77 option, which copies the algorithm from the predecessor key\&.
78 .sp
79 In prior releases, HMAC algorithms could be generated for use as TSIG keys, but that feature has been removed as of BIND 9\&.13\&.0\&. Use
80 \fBtsig\-keygen\fR
81 to generate TSIG keys\&.
82 .RE
83 .PP
84 \-b \fIkeysize\fR
85 .RS 4
86 Specifies the number of bits in the key\&. The choice of key size depends on the algorithm used\&. RSA keys must be between 1024 and 2048 bits\&. Diffie Hellman keys must be between 128 and 4096 bits\&. DSA keys must be between 512 and 1024 bits and an exact multiple of 64\&. HMAC keys must be between 1 and 512 bits\&. Elliptic curve algorithms don\*(Aqt need this parameter\&.
87 .sp
88 If the key size is not specified, some algorithms have pre\-defined defaults\&. For example, RSA keys for use as DNSSEC zone signing keys have a default size of 1024 bits; RSA keys for use as key signing keys (KSKs, generated with
89 \fB\-f KSK\fR) default to 2048 bits\&.
90 .RE
91 .PP
92 \-n \fInametype\fR
93 .RS 4
94 Specifies the owner type of the key\&. The value of
95 \fBnametype\fR
96 must either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)), USER (for a key associated with a user(KEY)) or OTHER (DNSKEY)\&. These values are case insensitive\&. Defaults to ZONE for DNSKEY generation\&.
97 .RE
98 .PP
99 \-3
100 .RS 4
101 Use an NSEC3\-capable algorithm to generate a DNSSEC key\&. If this option is used with an algorithm that has both NSEC and NSEC3 versions, then the NSEC3 version will be used; for example,
102 \fBdnssec\-keygen \-3a RSASHA1\fR
103 specifies the NSEC3RSASHA1 algorithm\&.
104 .RE
105 .PP
106 \-C
107 .RS 4
108 Compatibility mode: generates an old\-style key, without any metadata\&. By default,
109 \fBdnssec\-keygen\fR
110 will include the key\*(Aqs creation date in the metadata stored with the private key, and other dates may be set there as well (publication date, activation date, etc)\&. Keys that include this data may be incompatible with older versions of BIND; the
111 \fB\-C\fR
112 option suppresses them\&.
113 .RE
114 .PP
115 \-c \fIclass\fR
116 .RS 4
117 Indicates that the DNS record containing the key should have the specified class\&. If not specified, class IN is used\&.
118 .RE
119 .PP
120 \-E \fIengine\fR
121 .RS 4
122 Specifies the cryptographic hardware to use, when applicable\&.
123 .sp
124 When BIND is built with OpenSSL PKCS#11 support, this defaults to the string "pkcs11", which identifies an OpenSSL engine that can drive a cryptographic accelerator or hardware service module\&. When BIND is built with native PKCS#11 cryptography (\-\-enable\-native\-pkcs11), it defaults to the path of the PKCS#11 provider library specified via "\-\-with\-pkcs11"\&.
125 .RE
126 .PP
127 \-f \fIflag\fR
128 .RS 4
129 Set the specified flag in the flag field of the KEY/DNSKEY record\&. The only recognized flags are KSK (Key Signing Key) and REVOKE\&.
130 .RE
131 .PP
132 \-G
133 .RS 4
134 Generate a key, but do not publish it or sign with it\&. This option is incompatible with \-P and \-A\&.
135 .RE
136 .PP
137 \-g \fIgenerator\fR
138 .RS 4
139 If generating a Diffie Hellman key, use this generator\&. Allowed values are 2 and 5\&. If no generator is specified, a known prime from RFC 2539 will be used if possible; otherwise the default is 2\&.
140 .RE
141 .PP
142 \-h
143 .RS 4
144 Prints a short summary of the options and arguments to
145 \fBdnssec\-keygen\fR\&.
146 .RE
147 .PP
148 \-K \fIdirectory\fR
149 .RS 4
150 Sets the directory in which the key files are to be written\&.
151 .RE
152 .PP
153 \-k
154 .RS 4
155 Deprecated in favor of \-T KEY\&.
156 .RE
157 .PP
158 \-L \fIttl\fR
159 .RS 4
160 Sets the default TTL to use for this key when it is converted into a DNSKEY RR\&. If the key is imported into a zone, this is the TTL that will be used for it, unless there was already a DNSKEY RRset in place, in which case the existing TTL would take precedence\&. If this value is not set and there is no existing DNSKEY RRset, the TTL will default to the SOA TTL\&. Setting the default TTL to
161 0
162 or
163 none
164 is the same as leaving it unset\&.
165 .RE
166 .PP
167 \-p \fIprotocol\fR
168 .RS 4
169 Sets the protocol value for the generated key\&. The protocol is a number between 0 and 255\&. The default is 3 (DNSSEC)\&. Other possible values for this argument are listed in RFC 2535 and its successors\&.
170 .RE
171 .PP
172 \-q
173 .RS 4
174 Quiet mode: Suppresses unnecessary output, including progress indication\&. Without this option, when
175 \fBdnssec\-keygen\fR
176 is run interactively to generate an RSA or DSA key pair, it will print a string of symbols to
177 stderr
178 indicating the progress of the key generation\&. A \*(Aq\&.\*(Aq indicates that a random number has been found which passed an initial sieve test; \*(Aq+\*(Aq means a number has passed a single round of the Miller\-Rabin primality test; a space means that the number has passed all the tests and is a satisfactory key\&.
179 .RE
180 .PP
181 \-S \fIkey\fR
182 .RS 4
183 Create a new key which is an explicit successor to an existing key\&. The name, algorithm, size, and type of the key will be set to match the existing key\&. The activation date of the new key will be set to the inactivation date of the existing one\&. The publication date will be set to the activation date minus the prepublication interval, which defaults to 30 days\&.
184 .RE
185 .PP
186 \-s \fIstrength\fR
187 .RS 4
188 Specifies the strength value of the key\&. The strength is a number between 0 and 15, and currently has no defined purpose in DNSSEC\&.
189 .RE
190 .PP
191 \-T \fIrrtype\fR
192 .RS 4
193 Specifies the resource record type to use for the key\&.
194 \fBrrtype\fR
195 must be either DNSKEY or KEY\&. The default is DNSKEY when using a DNSSEC algorithm, but it can be overridden to KEY for use with SIG(0)\&.
196 Specifying any TSIG algorithm (HMAC\-* or DH) with
197 \fB\-a\fR
198 forces this option to KEY\&.
199 .RE
200 .PP
201 \-t \fItype\fR
202 .RS 4
203 Indicates the use of the key\&.
204 \fBtype\fR
205 must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF\&. The default is AUTHCONF\&. AUTH refers to the ability to authenticate data, and CONF the ability to encrypt data\&.
206 .RE
207 .PP
208 \-v \fIlevel\fR
209 .RS 4
210 Sets the debugging level\&.
211 .RE
212 .PP
213 \-V
214 .RS 4
215 Prints version information\&.
216 .RE
217 .SH "TIMING OPTIONS"
218 .PP
219 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS\&. If the argument begins with a \*(Aq+\*(Aq or \*(Aq\-\*(Aq, it is interpreted as an offset from the present time\&. For convenience, if such an offset is followed by one of the suffixes \*(Aqy\*(Aq, \*(Aqmo\*(Aq, \*(Aqw\*(Aq, \*(Aqd\*(Aq, \*(Aqh\*(Aq, or \*(Aqmi\*(Aq, then the offset is computed in years (defined as 365 24\-hour days, ignoring leap years), months (defined as 30 24\-hour days), weeks, days, hours, or minutes, respectively\&. Without a suffix, the offset is computed in seconds\&. To explicitly prevent a date from being set, use \*(Aqnone\*(Aq or \*(Aqnever\*(Aq\&.
220 .PP
221 \-P \fIdate/offset\fR
222 .RS 4
223 Sets the date on which a key is to be published to the zone\&. After that date, the key will be included in the zone but will not be used to sign it\&. If not set, and if the \-G option has not been used, the default is "now"\&.
224 .RE
225 .PP
226 \-P sync \fIdate/offset\fR
227 .RS 4
228 Sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone\&.
229 .RE
230 .PP
231 \-A \fIdate/offset\fR
232 .RS 4
233 Sets the date on which the key is to be activated\&. After that date, the key will be included in the zone and used to sign it\&. If not set, and if the \-G option has not been used, the default is "now"\&. If set, if and \-P is not set, then the publication date will be set to the activation date minus the prepublication interval\&.
234 .RE
235 .PP
236 \-R \fIdate/offset\fR
237 .RS 4
238 Sets the date on which the key is to be revoked\&. After that date, the key will be flagged as revoked\&. It will be included in the zone and will be used to sign it\&.
239 .RE
240 .PP
241 \-I \fIdate/offset\fR
242 .RS 4
243 Sets the date on which the key is to be retired\&. After that date, the key will still be included in the zone, but it will not be used to sign it\&.
244 .RE
245 .PP
246 \-D \fIdate/offset\fR
247 .RS 4
248 Sets the date on which the key is to be deleted\&. After that date, the key will no longer be included in the zone\&. (It may remain in the key repository, however\&.)
249 .RE
250 .PP
251 \-D sync \fIdate/offset\fR
252 .RS 4
253 Sets the date on which the CDS and CDNSKEY records that match this key are to be deleted\&.
254 .RE
255 .PP
256 \-i \fIinterval\fR
257 .RS 4
258 Sets the prepublication interval for a key\&. If set, then the publication and activation dates must be separated by at least this much time\&. If the activation date is specified but the publication date isn\*(Aqt, then the publication date will default to this much time before the activation date; conversely, if the publication date is specified but activation date isn\*(Aqt, then activation will be set to this much time after publication\&.
259 .sp
260 If the key is being created as an explicit successor to another key, then the default prepublication interval is 30 days; otherwise it is zero\&.
261 .sp
262 As with date offsets, if the argument is followed by one of the suffixes \*(Aqy\*(Aq, \*(Aqmo\*(Aq, \*(Aqw\*(Aq, \*(Aqd\*(Aq, \*(Aqh\*(Aq, or \*(Aqmi\*(Aq, then the interval is measured in years, months, weeks, days, hours, or minutes, respectively\&. Without a suffix, the interval is measured in seconds\&.
263 .RE
264 .SH "GENERATED KEYS"
265 .PP
266 When
267 \fBdnssec\-keygen\fR
268 completes successfully, it prints a string of the form
269 Knnnn\&.+aaa+iiiii
270 to the standard output\&. This is an identification string for the key it has generated\&.
271 .sp
272 .RS 4
273 .ie n \{\
274 \h'-04'\(bu\h'+03'\c
275 .\}
276 .el \{\
277 .sp -1
278 .IP \(bu 2.3
279 .\}
280 nnnn
281 is the key name\&.
282 .RE
283 .sp
284 .RS 4
285 .ie n \{\
286 \h'-04'\(bu\h'+03'\c
287 .\}
288 .el \{\
289 .sp -1
290 .IP \(bu 2.3
291 .\}
292 aaa
293 is the numeric representation of the algorithm\&.
294 .RE
295 .sp
296 .RS 4
297 .ie n \{\
298 \h'-04'\(bu\h'+03'\c
299 .\}
300 .el \{\
301 .sp -1
302 .IP \(bu 2.3
303 .\}
304 iiiii
305 is the key identifier (or footprint)\&.
306 .RE
307 .PP
308 \fBdnssec\-keygen\fR
309 creates two files, with names based on the printed string\&.
310 Knnnn\&.+aaa+iiiii\&.key
311 contains the public key, and
312 Knnnn\&.+aaa+iiiii\&.private
313 contains the private key\&.
314 .PP
315 The
316 \&.key
317 file contains a DNS KEY record that can be inserted into a zone file (directly or with a $INCLUDE statement)\&.
318 .PP
319 The
320 \&.private
321 file contains algorithm\-specific fields\&. For obvious security reasons, this file does not have general read permission\&.
322 .PP
323 Both
324 \&.key
325 and
326 \&.private
327 files are generated for symmetric cryptography algorithms such as HMAC\-MD5, even though the public and private key are equivalent\&.
328 .SH "EXAMPLE"
329 .PP
330 To generate an ECDSAP256SHA256 key for the domain
331 \fBexample\&.com\fR, the following command would be issued:
332 .PP
333 \fBdnssec\-keygen \-a ECDSAP256SHA256 \-n ZONE example\&.com\fR
334 .PP
335 The command would print a string of the form:
336 .PP
337 \fBKexample\&.com\&.+013+26160\fR
338 .PP
339 In this example,
340 \fBdnssec\-keygen\fR
341 creates the files
342 Kexample\&.com\&.+013+26160\&.key
343 and
344 Kexample\&.com\&.+013+26160\&.private\&.
345 .SH "SEE ALSO"
346 .PP
347 \fBdnssec-signzone\fR(8),
348 BIND 9 Administrator Reference Manual,
349 RFC 2539,
350 RFC 2845,
351 RFC 4034\&.
352 .SH "AUTHOR"
353 .PP
354 \fBInternet Systems Consortium, Inc\&.\fR
355 .SH "COPYRIGHT"
356 .br
357 Copyright \(co 2000-2005, 2007-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
358 .br