Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_13_...
[ipreg/bind9.git] / bin / dnssec / dnssec-keygen.8
CommitLineData
b4d3f782 1.\" Copyright (C) 2000-2005, 2007-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
60e5e10f 2.\"
6807a2dc
TU
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/.
83217b5f 6.\"
60e5e10f
RA
7.hy 0
8.ad l
2eeb74d1
TU
9'\" t
10.\" Title: dnssec-keygen
ca67ebfe 11.\" Author:
fd2597f7 12.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
e62b9c9c 13.\" Date: August 21, 2015
ca67ebfe 14.\" Manual: BIND9
2eeb74d1
TU
15.\" Source: ISC
16.\" Language: English
ca67ebfe 17.\"
e62b9c9c 18.TH "DNSSEC\-KEYGEN" "8" "August 21, 2015" "ISC" "BIND9"
2eeb74d1
TU
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.\" -----------------------------------------------------------------
ca67ebfe
AU
31.\" disable hyphenation
32.nh
33.\" disable justification (adjust text to left margin only)
34.ad l
2eeb74d1
TU
35.\" -----------------------------------------------------------------
36.\" * MAIN CONTENT STARTS HERE *
37.\" -----------------------------------------------------------------
ca67ebfe 38.SH "NAME"
2eeb74d1 39dnssec-keygen \- DNSSEC key generation tool
60e5e10f 40.SH "SYNOPSIS"
fd2597f7 41.HP \w'\fBdnssec\-keygen\fR\ 'u
9536688b 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}
0b062f49
BW
43.SH "DESCRIPTION"
44.PP
ca67ebfe 45\fBdnssec\-keygen\fR
2eeb74d1 46generates 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\&.
ad671240
AU
47.PP
48The
49\fBname\fR
2eeb74d1 50of 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\&.
e640ea93
TU
51.PP
52The
53\fBdnssec\-keymgr\fR
54command 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
57may be preferable to direct use of
58\fBdnssec\-keygen\fR\&.
0b062f49 59.SH "OPTIONS"
ca67ebfe 60.PP
60e5e10f 61\-a \fIalgorithm\fR
ca67ebfe 62.RS 4
2eeb74d1 63Selects the cryptographic algorithm\&. For DNSSEC keys, the value of
ca67ebfe 64\fBalgorithm\fR
b4d3f782 65must 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
e640ea93 66\fB\-T KEY\fR
a53e0320
TU
67option as well\&.
68.sp
db1cd0d9 69These 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
0a7ed886 70\fB\-3\fR
db1cd0d9 71option, then NSEC3RSASHA1 will be used instead\&.
ca67ebfe 72.sp
630d1a9b
TU
73This parameter
74\fImust\fR
75be specified except when using the
e640ea93 76\fB\-S\fR
630d1a9b
TU
77option, which copies the algorithm from the predecessor key\&.
78.sp
79In 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
81to generate TSIG keys\&.
ca67ebfe
AU
82.RE
83.PP
60e5e10f 84\-b \fIkeysize\fR
ca67ebfe 85.RS 4
f5fa6553 86Specifies 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\&.
ca67ebfe 87.sp
e640ea93
TU
88If 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\&.
ca67ebfe
AU
90.RE
91.PP
60e5e10f 92\-n \fInametype\fR
ca67ebfe 93.RS 4
2eeb74d1 94Specifies the owner type of the key\&. The value of
ca67ebfe 95\fBnametype\fR
2eeb74d1 96must 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\&.
ca67ebfe
AU
97.RE
98.PP
0a7ed886
AU
99\-3
100.RS 4
e640ea93
TU
101Use 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
103specifies the NSEC3RSASHA1 algorithm\&.
0a7ed886
AU
104.RE
105.PP
106\-C
107.RS 4
2eeb74d1 108Compatibility mode: generates an old\-style key, without any metadata\&. By default,
0a7ed886 109\fBdnssec\-keygen\fR
2eeb74d1 110will 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
0a7ed886 111\fB\-C\fR
2eeb74d1 112option suppresses them\&.
0a7ed886
AU
113.RE
114.PP
60e5e10f 115\-c \fIclass\fR
ca67ebfe 116.RS 4
2eeb74d1 117Indicates that the DNS record containing the key should have the specified class\&. If not specified, class IN is used\&.
ca67ebfe
AU
118.RE
119.PP
8ec3c085
AU
120\-E \fIengine\fR
121.RS 4
2eeb74d1 122Specifies the cryptographic hardware to use, when applicable\&.
6ea23853 123.sp
2eeb74d1 124When 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"\&.
8ec3c085
AU
125.RE
126.PP
60e5e10f 127\-f \fIflag\fR
ca67ebfe 128.RS 4
2eeb74d1 129Set the specified flag in the flag field of the KEY/DNSKEY record\&. The only recognized flags are KSK (Key Signing Key) and REVOKE\&.
ca67ebfe
AU
130.RE
131.PP
f8e3e03c
AU
132\-G
133.RS 4
2eeb74d1 134Generate a key, but do not publish it or sign with it\&. This option is incompatible with \-P and \-A\&.
f8e3e03c
AU
135.RE
136.PP
60e5e10f 137\-g \fIgenerator\fR
ca67ebfe 138.RS 4
2eeb74d1 139If 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\&.
ca67ebfe
AU
140.RE
141.PP
60e5e10f 142\-h
ca67ebfe
AU
143.RS 4
144Prints a short summary of the options and arguments to
2eeb74d1 145\fBdnssec\-keygen\fR\&.
ca67ebfe
AU
146.RE
147.PP
0a7ed886
AU
148\-K \fIdirectory\fR
149.RS 4
2eeb74d1 150Sets the directory in which the key files are to be written\&.
0a7ed886
AU
151.RE
152.PP
60e5e10f 153\-k
ca67ebfe 154.RS 4
2eeb74d1 155Deprecated in favor of \-T KEY\&.
ca67ebfe
AU
156.RE
157.PP
a3f8c8e2
AU
158\-L \fIttl\fR
159.RS 4
2eeb74d1 160Sets 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
a3f8c8e2
AU
1610
162or
163none
2eeb74d1 164is the same as leaving it unset\&.
a3f8c8e2
AU
165.RE
166.PP
60e5e10f 167\-p \fIprotocol\fR
ca67ebfe 168.RS 4
2eeb74d1 169Sets 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\&.
ca67ebfe
AU
170.RE
171.PP
575e15fe
AU
172\-q
173.RS 4
2eeb74d1 174Quiet mode: Suppresses unnecessary output, including progress indication\&. Without this option, when
575e15fe
AU
175\fBdnssec\-keygen\fR
176is run interactively to generate an RSA or DSA key pair, it will print a string of symbols to
2eeb74d1
TU
177stderr
178indicating 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\&.
575e15fe
AU
179.RE
180.PP
3acf5eb9
AU
181\-S \fIkey\fR
182.RS 4
2eeb74d1 183Create 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\&.
3acf5eb9
AU
184.RE
185.PP
60e5e10f 186\-s \fIstrength\fR
ca67ebfe 187.RS 4
2eeb74d1 188Specifies the strength value of the key\&. The strength is a number between 0 and 15, and currently has no defined purpose in DNSSEC\&.
ca67ebfe
AU
189.RE
190.PP
0a7ed886
AU
191\-T \fIrrtype\fR
192.RS 4
2eeb74d1 193Specifies the resource record type to use for the key\&.
0a7ed886 194\fBrrtype\fR
2eeb74d1 195must 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)\&.
e640ea93
TU
196Specifying any TSIG algorithm (HMAC\-* or DH) with
197\fB\-a\fR
198forces this option to KEY\&.
0a7ed886
AU
199.RE
200.PP
60e5e10f 201\-t \fItype\fR
ca67ebfe 202.RS 4
2eeb74d1 203Indicates the use of the key\&.
ca67ebfe 204\fBtype\fR
2eeb74d1 205must 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\&.
ca67ebfe
AU
206.RE
207.PP
60e5e10f 208\-v \fIlevel\fR
ca67ebfe 209.RS 4
2eeb74d1 210Sets the debugging level\&.
ca67ebfe 211.RE
6f120589
TU
212.PP
213\-V
214.RS 4
2eeb74d1 215Prints version information\&.
6f120589 216.RE
0a7ed886
AU
217.SH "TIMING OPTIONS"
218.PP
2eeb74d1 219Dates 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\&.
0a7ed886
AU
220.PP
221\-P \fIdate/offset\fR
222.RS 4
2eeb74d1 223Sets 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"\&.
0a7ed886
AU
224.RE
225.PP
e62b9c9c
TU
226\-P sync \fIdate/offset\fR
227.RS 4
228Sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone\&.
229.RE
230.PP
0a7ed886
AU
231\-A \fIdate/offset\fR
232.RS 4
2eeb74d1 233Sets 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\&.
0a7ed886
AU
234.RE
235.PP
236\-R \fIdate/offset\fR
237.RS 4
2eeb74d1 238Sets 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\&.
0a7ed886
AU
239.RE
240.PP
f8e3e03c 241\-I \fIdate/offset\fR
0a7ed886 242.RS 4
2eeb74d1 243Sets 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\&.
0a7ed886
AU
244.RE
245.PP
246\-D \fIdate/offset\fR
247.RS 4
2eeb74d1 248Sets 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\&.)
0a7ed886 249.RE
3acf5eb9 250.PP
e62b9c9c
TU
251\-D sync \fIdate/offset\fR
252.RS 4
253Sets the date on which the CDS and CDNSKEY records that match this key are to be deleted\&.
254.RE
255.PP
3acf5eb9
AU
256\-i \fIinterval\fR
257.RS 4
2eeb74d1 258Sets 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\&.
3acf5eb9 259.sp
2eeb74d1 260If the key is being created as an explicit successor to another key, then the default prepublication interval is 30 days; otherwise it is zero\&.
3acf5eb9 261.sp
2eeb74d1 262As 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\&.
3acf5eb9 263.RE
0b062f49
BW
264.SH "GENERATED KEYS"
265.PP
ca67ebfe
AU
266When
267\fBdnssec\-keygen\fR
268completes successfully, it prints a string of the form
2eeb74d1
TU
269Knnnn\&.+aaa+iiiii
270to 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.\}
280nnnn
281is 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.\}
292aaa
293is 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.\}
304iiiii
305is the key identifier (or footprint)\&.
306.RE
8ffa8320 307.PP
ca67ebfe 308\fBdnssec\-keygen\fR
2eeb74d1
TU
309creates two files, with names based on the printed string\&.
310Knnnn\&.+aaa+iiiii\&.key
ca67ebfe 311contains the public key, and
2eeb74d1
TU
312Knnnn\&.+aaa+iiiii\&.private
313contains the private key\&.
0b062f49 314.PP
ca67ebfe 315The
2eeb74d1
TU
316\&.key
317file contains a DNS KEY record that can be inserted into a zone file (directly or with a $INCLUDE statement)\&.
8ffa8320 318.PP
ca67ebfe 319The
2eeb74d1
TU
320\&.private
321file contains algorithm\-specific fields\&. For obvious security reasons, this file does not have general read permission\&.
8ffa8320 322.PP
ca67ebfe 323Both
2eeb74d1 324\&.key
ca67ebfe 325and
2eeb74d1 326\&.private
e76f1137 327files are generated for symmetric cryptography algorithms such as HMAC\-MD5, even though the public and private key are equivalent\&.
0b062f49
BW
328.SH "EXAMPLE"
329.PP
5bd85525 330To generate an ECDSAP256SHA256 key for the domain
2eeb74d1 331\fBexample\&.com\fR, the following command would be issued:
0b062f49 332.PP
5bd85525 333\fBdnssec\-keygen \-a ECDSAP256SHA256 \-n ZONE example\&.com\fR
0b062f49
BW
334.PP
335The command would print a string of the form:
336.PP
5bd85525 337\fBKexample\&.com\&.+013+26160\fR
0b062f49 338.PP
ca67ebfe
AU
339In this example,
340\fBdnssec\-keygen\fR
341creates the files
5bd85525 342Kexample\&.com\&.+013+26160\&.key
ca67ebfe 343and
5bd85525 344Kexample\&.com\&.+013+26160\&.private\&.
0b062f49
BW
345.SH "SEE ALSO"
346.PP
2eeb74d1 347\fBdnssec-signzone\fR(8),
ca67ebfe
AU
348BIND 9 Administrator Reference Manual,
349RFC 2539,
350RFC 2845,
2eeb74d1 351RFC 4034\&.
0b062f49
BW
352.SH "AUTHOR"
353.PP
2eeb74d1 354\fBInternet Systems Consortium, Inc\&.\fR
ca67ebfe 355.SH "COPYRIGHT"
ca67ebfe 356.br
b4d3f782 357Copyright \(co 2000-2005, 2007-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
ca67ebfe 358.br