Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_13_...
[ipreg/bind9.git] / bin / dnssec / dnssec-keyfromlabel.8
1 .\" Copyright (C) 2008-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-keyfromlabel
11 .\" Author:
12 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
13 .\" Date: August 27, 2015
14 .\" Manual: BIND9
15 .\" Source: ISC
16 .\" Language: English
17 .\"
18 .TH "DNSSEC\-KEYFROMLABEL" "8" "August 27, 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-keyfromlabel \- DNSSEC key generation tool
40 .SH "SYNOPSIS"
41 .HP \w'\fBdnssec\-keyfromlabel\fR\ 'u
42 \fBdnssec\-keyfromlabel\fR {\-l\ \fIlabel\fR} [\fB\-3\fR] [\fB\-a\ \fR\fB\fIalgorithm\fR\fR] [\fB\-A\ \fR\fB\fIdate/offset\fR\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\-I\ \fR\fB\fIdate/offset\fR\fR] [\fB\-i\ \fR\fB\fIinterval\fR\fR] [\fB\-k\fR] [\fB\-K\ \fR\fB\fIdirectory\fR\fR] [\fB\-L\ \fR\fB\fIttl\fR\fR] [\fB\-n\ \fR\fB\fInametype\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\-R\ \fR\fB\fIdate/offset\fR\fR] [\fB\-S\ \fR\fB\fIkey\fR\fR] [\fB\-t\ \fR\fB\fItype\fR\fR] [\fB\-v\ \fR\fB\fIlevel\fR\fR] [\fB\-V\fR] [\fB\-y\fR] {name}
43 .SH "DESCRIPTION"
44 .PP
45 \fBdnssec\-keyfromlabel\fR
46 generates a key pair of files that referencing a key object stored in a cryptographic hardware service module (HSM)\&. The private key file can be used for DNSSEC signing of zone data as if it were a conventional signing key created by
47 \fBdnssec\-keygen\fR, but the key material is stored within the HSM, and the actual signing takes place there\&.
48 .PP
49 The
50 \fBname\fR
51 of the key is specified on the command line\&. This must match the name of the zone for which the key is being generated\&.
52 .SH "OPTIONS"
53 .PP
54 \-a \fIalgorithm\fR
55 .RS 4
56 Selects the cryptographic algorithm\&. The value of
57 \fBalgorithm\fR
58 must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448\&.
59 .sp
60 If no algorithm is specified, then RSASHA1 will be used by default, unless the
61 \fB\-3\fR
62 option is specified, in which case NSEC3RSASHA1 will be used instead\&. (If
63 \fB\-3\fR
64 is used and an algorithm is specified, that algorithm will be checked for compatibility with NSEC3\&.)
65 .sp
66 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
67 \fB\-3\fR
68 option, then NSEC3RSASHA1 will be used instead\&.
69 .sp
70 As of BIND 9\&.12\&.0, this option is mandatory except when using the
71 \fB\-S\fR
72 option (which copies the algorithm from the predecessory key)\&. Previously, the default for newly generated keys was RSASHA1\&.
73 .RE
74 .PP
75 \-3
76 .RS 4
77 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,
78 \fBdnssec\-keygen \-3a RSASHA1\fR
79 specifies the NSEC3RSASHA1 algorithm\&.
80 .RE
81 .PP
82 \-E \fIengine\fR
83 .RS 4
84 Specifies the cryptographic hardware to use\&.
85 .sp
86 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"\&.
87 .RE
88 .PP
89 \-l \fIlabel\fR
90 .RS 4
91 Specifies the label for a key pair in the crypto hardware\&.
92 .sp
93 When
94 BIND
95 9 is built with OpenSSL\-based PKCS#11 support, the label is an arbitrary string that identifies a particular key\&. It may be preceded by an optional OpenSSL engine name, followed by a colon, as in "pkcs11:\fIkeylabel\fR"\&.
96 .sp
97 When
98 BIND
99 9 is built with native PKCS#11 support, the label is a PKCS#11 URI string in the format "pkcs11:\fBkeyword\fR=\fIvalue\fR[;\fBkeyword\fR=\fIvalue\fR;\&.\&.\&.]" Keywords include "token", which identifies the HSM; "object", which identifies the key; and "pin\-source", which identifies a file from which the HSM\*(Aqs PIN code can be obtained\&. The label will be stored in the on\-disk "private" file\&.
100 .sp
101 If the label contains a
102 \fBpin\-source\fR
103 field, tools using the generated key files will be able to use the HSM for signing and other operations without any need for an operator to manually enter a PIN\&. Note: Making the HSM\*(Aqs PIN accessible in this manner may reduce the security advantage of using an HSM; be sure this is what you want to do before making use of this feature\&.
104 .RE
105 .PP
106 \-n \fInametype\fR
107 .RS 4
108 Specifies the owner type of the key\&. The value of
109 \fBnametype\fR
110 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\&.
111 .RE
112 .PP
113 \-C
114 .RS 4
115 Compatibility mode: generates an old\-style key, without any metadata\&. By default,
116 \fBdnssec\-keyfromlabel\fR
117 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
118 \fB\-C\fR
119 option suppresses them\&.
120 .RE
121 .PP
122 \-c \fIclass\fR
123 .RS 4
124 Indicates that the DNS record containing the key should have the specified class\&. If not specified, class IN is used\&.
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 \-h
138 .RS 4
139 Prints a short summary of the options and arguments to
140 \fBdnssec\-keyfromlabel\fR\&.
141 .RE
142 .PP
143 \-K \fIdirectory\fR
144 .RS 4
145 Sets the directory in which the key files are to be written\&.
146 .RE
147 .PP
148 \-k
149 .RS 4
150 Generate KEY records rather than DNSKEY records\&.
151 .RE
152 .PP
153 \-L \fIttl\fR
154 .RS 4
155 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\&. Setting the default TTL to
156 0
157 or
158 none
159 removes it\&.
160 .RE
161 .PP
162 \-p \fIprotocol\fR
163 .RS 4
164 Sets the protocol value for the 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\&.
165 .RE
166 .PP
167 \-S \fIkey\fR
168 .RS 4
169 Generate a key as an explicit successor to an existing key\&. The name, algorithm, size, and type of the key will be set to match the predecessor\&. 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\&.
170 .RE
171 .PP
172 \-t \fItype\fR
173 .RS 4
174 Indicates the use of the key\&.
175 \fBtype\fR
176 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\&.
177 .RE
178 .PP
179 \-v \fIlevel\fR
180 .RS 4
181 Sets the debugging level\&.
182 .RE
183 .PP
184 \-V
185 .RS 4
186 Prints version information\&.
187 .RE
188 .PP
189 \-y
190 .RS 4
191 Allows DNSSEC key files to be generated even if the key ID would collide with that of an existing key, in the event of either key being revoked\&. (This is only safe to use if you are sure you won\*(Aqt be using RFC 5011 trust anchor maintenance with either of the keys involved\&.)
192 .RE
193 .SH "TIMING OPTIONS"
194 .PP
195 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\&.
196 .PP
197 \-P \fIdate/offset\fR
198 .RS 4
199 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"\&.
200 .RE
201 .PP
202 \-P sync \fIdate/offset\fR
203 .RS 4
204 Sets the date on which the CDS and CDNSKEY records which match this key are to be published to the zone\&.
205 .RE
206 .PP
207 \-A \fIdate/offset\fR
208 .RS 4
209 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"\&.
210 .RE
211 .PP
212 \-R \fIdate/offset\fR
213 .RS 4
214 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\&.
215 .RE
216 .PP
217 \-I \fIdate/offset\fR
218 .RS 4
219 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\&.
220 .RE
221 .PP
222 \-D \fIdate/offset\fR
223 .RS 4
224 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\&.)
225 .RE
226 .PP
227 \-D sync \fIdate/offset\fR
228 .RS 4
229 Sets the date on which the CDS and CDNSKEY records which match this key are to be deleted\&.
230 .RE
231 .PP
232 \-i \fIinterval\fR
233 .RS 4
234 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\&.
235 .sp
236 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\&.
237 .sp
238 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\&.
239 .RE
240 .SH "GENERATED KEY FILES"
241 .PP
242 When
243 \fBdnssec\-keyfromlabel\fR
244 completes successfully, it prints a string of the form
245 Knnnn\&.+aaa+iiiii
246 to the standard output\&. This is an identification string for the key files it has generated\&.
247 .sp
248 .RS 4
249 .ie n \{\
250 \h'-04'\(bu\h'+03'\c
251 .\}
252 .el \{\
253 .sp -1
254 .IP \(bu 2.3
255 .\}
256 nnnn
257 is the key name\&.
258 .RE
259 .sp
260 .RS 4
261 .ie n \{\
262 \h'-04'\(bu\h'+03'\c
263 .\}
264 .el \{\
265 .sp -1
266 .IP \(bu 2.3
267 .\}
268 aaa
269 is the numeric representation of the algorithm\&.
270 .RE
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 iiiii
281 is the key identifier (or footprint)\&.
282 .RE
283 .PP
284 \fBdnssec\-keyfromlabel\fR
285 creates two files, with names based on the printed string\&.
286 Knnnn\&.+aaa+iiiii\&.key
287 contains the public key, and
288 Knnnn\&.+aaa+iiiii\&.private
289 contains the private key\&.
290 .PP
291 The
292 \&.key
293 file contains a DNS KEY record that can be inserted into a zone file (directly or with a $INCLUDE statement)\&.
294 .PP
295 The
296 \&.private
297 file contains algorithm\-specific fields\&. For obvious security reasons, this file does not have general read permission\&.
298 .SH "SEE ALSO"
299 .PP
300 \fBdnssec-keygen\fR(8),
301 \fBdnssec-signzone\fR(8),
302 BIND 9 Administrator Reference Manual,
303 RFC 4034,
304 The PKCS#11 URI Scheme (draft\-pechanec\-pkcs11uri\-13)\&.
305 .SH "AUTHOR"
306 .PP
307 \fBInternet Systems Consortium, Inc\&.\fR
308 .SH "COPYRIGHT"
309 .br
310 Copyright \(co 2008-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
311 .br