Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-keyfromlabel.8
CommitLineData
b4d3f782 1.\" Copyright (C) 2008-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
90f35c2f 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/.
90f35c2f 6.\"
90f35c2f
FD
7.hy 0
8.ad l
2eeb74d1
TU
9'\" t
10.\" Title: dnssec-keyfromlabel
90f35c2f 11.\" Author:
fd2597f7 12.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
e62b9c9c 13.\" Date: August 27, 2015
90f35c2f 14.\" Manual: BIND9
2eeb74d1
TU
15.\" Source: ISC
16.\" Language: English
90f35c2f 17.\"
e62b9c9c 18.TH "DNSSEC\-KEYFROMLABEL" "8" "August 27, 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.\" -----------------------------------------------------------------
90f35c2f
FD
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.\" -----------------------------------------------------------------
90f35c2f 38.SH "NAME"
2eeb74d1 39dnssec-keyfromlabel \- DNSSEC key generation tool
90f35c2f 40.SH "SYNOPSIS"
fd2597f7 41.HP \w'\fBdnssec\-keyfromlabel\fR\ 'u
e62b9c9c 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}
90f35c2f
FD
43.SH "DESCRIPTION"
44.PP
45\fBdnssec\-keyfromlabel\fR
2eeb74d1
TU
46generates 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\&.
c7d32c0b
AU
48.PP
49The
50\fBname\fR
2eeb74d1 51of the key is specified on the command line\&. This must match the name of the zone for which the key is being generated\&.
90f35c2f
FD
52.SH "OPTIONS"
53.PP
54\-a \fIalgorithm\fR
55.RS 4
2eeb74d1 56Selects the cryptographic algorithm\&. The value of
90f35c2f 57\fBalgorithm\fR
b4d3f782 58must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519 or ED448\&.
90f35c2f 59.sp
2a6d4c99
AU
60If no algorithm is specified, then RSASHA1 will be used by default, unless the
61\fB\-3\fR
2eeb74d1 62option is specified, in which case NSEC3RSASHA1 will be used instead\&. (If
8e821eea 63\fB\-3\fR
2eeb74d1 64is used and an algorithm is specified, that algorithm will be checked for compatibility with NSEC3\&.)
2a6d4c99 65.sp
db1cd0d9 66These 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
e640ea93 67\fB\-3\fR
db1cd0d9 68option, then NSEC3RSASHA1 will be used instead\&.
90f35c2f 69.sp
e640ea93
TU
70As of BIND 9\&.12\&.0, this option is mandatory except when using the
71\fB\-S\fR
72option (which copies the algorithm from the predecessory key)\&. Previously, the default for newly generated keys was RSASHA1\&.
90f35c2f
FD
73.RE
74.PP
2a6d4c99
AU
75\-3
76.RS 4
e640ea93
TU
77Use 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
79specifies the NSEC3RSASHA1 algorithm\&.
2a6d4c99
AU
80.RE
81.PP
8ec3c085
AU
82\-E \fIengine\fR
83.RS 4
2eeb74d1 84Specifies the cryptographic hardware to use\&.
6ea23853 85.sp
2eeb74d1 86When 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
87.RE
88.PP
90f35c2f
FD
89\-l \fIlabel\fR
90.RS 4
2eeb74d1 91Specifies the label for a key pair in the crypto hardware\&.
bbbf2e27
TU
92.sp
93When
94BIND
2eeb74d1 959 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"\&.
bbbf2e27
TU
96.sp
97When
98BIND
2eeb74d1 999 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\&.
bbbf2e27
TU
100.sp
101If the label contains a
102\fBpin\-source\fR
2eeb74d1 103field, 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\&.
90f35c2f
FD
104.RE
105.PP
106\-n \fInametype\fR
107.RS 4
2eeb74d1 108Specifies the owner type of the key\&. The value of
90f35c2f 109\fBnametype\fR
2eeb74d1 110must 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\&.
90f35c2f
FD
111.RE
112.PP
c7d32c0b
AU
113\-C
114.RS 4
2eeb74d1 115Compatibility mode: generates an old\-style key, without any metadata\&. By default,
c7d32c0b 116\fBdnssec\-keyfromlabel\fR
2eeb74d1 117will 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
c7d32c0b 118\fB\-C\fR
2eeb74d1 119option suppresses them\&.
c7d32c0b
AU
120.RE
121.PP
90f35c2f
FD
122\-c \fIclass\fR
123.RS 4
2eeb74d1 124Indicates that the DNS record containing the key should have the specified class\&. If not specified, class IN is used\&.
90f35c2f
FD
125.RE
126.PP
127\-f \fIflag\fR
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\&.
90f35c2f
FD
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
90f35c2f
FD
137\-h
138.RS 4
139Prints a short summary of the options and arguments to
2eeb74d1 140\fBdnssec\-keyfromlabel\fR\&.
90f35c2f
FD
141.RE
142.PP
0a7ed886
AU
143\-K \fIdirectory\fR
144.RS 4
2eeb74d1 145Sets the directory in which the key files are to be written\&.
0a7ed886
AU
146.RE
147.PP
90f35c2f
FD
148\-k
149.RS 4
2eeb74d1 150Generate KEY records rather than DNSKEY records\&.
90f35c2f
FD
151.RE
152.PP
a3f8c8e2
AU
153\-L \fIttl\fR
154.RS 4
2eeb74d1 155Sets 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
a3f8c8e2
AU
1560
157or
158none
2eeb74d1 159removes it\&.
a3f8c8e2
AU
160.RE
161.PP
90f35c2f
FD
162\-p \fIprotocol\fR
163.RS 4
2eeb74d1 164Sets 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\&.
90f35c2f
FD
165.RE
166.PP
794b79e6
TU
167\-S \fIkey\fR
168.RS 4
2eeb74d1 169Generate 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\&.
794b79e6
TU
170.RE
171.PP
90f35c2f
FD
172\-t \fItype\fR
173.RS 4
2eeb74d1 174Indicates the use of the key\&.
90f35c2f 175\fBtype\fR
2eeb74d1 176must 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\&.
90f35c2f
FD
177.RE
178.PP
179\-v \fIlevel\fR
180.RS 4
2eeb74d1 181Sets the debugging level\&.
90f35c2f 182.RE
a3416b0a 183.PP
6f120589
TU
184\-V
185.RS 4
2eeb74d1 186Prints version information\&.
6f120589
TU
187.RE
188.PP
a3416b0a
AU
189\-y
190.RS 4
2eeb74d1 191Allows 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\&.)
a3416b0a 192.RE
c7d32c0b
AU
193.SH "TIMING OPTIONS"
194.PP
2eeb74d1 195Dates 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\&.
c7d32c0b
AU
196.PP
197\-P \fIdate/offset\fR
198.RS 4
2eeb74d1 199Sets 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"\&.
c7d32c0b
AU
200.RE
201.PP
e62b9c9c
TU
202\-P sync \fIdate/offset\fR
203.RS 4
204Sets the date on which the CDS and CDNSKEY records which match this key are to be published to the zone\&.
205.RE
206.PP
c7d32c0b
AU
207\-A \fIdate/offset\fR
208.RS 4
2eeb74d1 209Sets 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"\&.
c7d32c0b
AU
210.RE
211.PP
212\-R \fIdate/offset\fR
213.RS 4
2eeb74d1 214Sets 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\&.
c7d32c0b
AU
215.RE
216.PP
79cf9524 217\-I \fIdate/offset\fR
c7d32c0b 218.RS 4
2eeb74d1 219Sets 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\&.
c7d32c0b
AU
220.RE
221.PP
222\-D \fIdate/offset\fR
223.RS 4
2eeb74d1 224Sets 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\&.)
c7d32c0b 225.RE
794b79e6 226.PP
e62b9c9c
TU
227\-D sync \fIdate/offset\fR
228.RS 4
229Sets the date on which the CDS and CDNSKEY records which match this key are to be deleted\&.
230.RE
231.PP
794b79e6
TU
232\-i \fIinterval\fR
233.RS 4
2eeb74d1 234Sets 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\&.
794b79e6 235.sp
2eeb74d1 236If the key is being created as an explicit successor to another key, then the default prepublication interval is 30 days; otherwise it is zero\&.
794b79e6 237.sp
2eeb74d1 238As 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\&.
794b79e6 239.RE
90f35c2f
FD
240.SH "GENERATED KEY FILES"
241.PP
242When
243\fBdnssec\-keyfromlabel\fR
244completes successfully, it prints a string of the form
2eeb74d1
TU
245Knnnn\&.+aaa+iiiii
246to 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.\}
256nnnn
257is 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.\}
268aaa
269is 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.\}
280iiiii
281is the key identifier (or footprint)\&.
282.RE
90f35c2f
FD
283.PP
284\fBdnssec\-keyfromlabel\fR
2eeb74d1
TU
285creates two files, with names based on the printed string\&.
286Knnnn\&.+aaa+iiiii\&.key
90f35c2f 287contains the public key, and
2eeb74d1
TU
288Knnnn\&.+aaa+iiiii\&.private
289contains the private key\&.
90f35c2f
FD
290.PP
291The
2eeb74d1
TU
292\&.key
293file contains a DNS KEY record that can be inserted into a zone file (directly or with a $INCLUDE statement)\&.
90f35c2f
FD
294.PP
295The
2eeb74d1
TU
296\&.private
297file contains algorithm\-specific fields\&. For obvious security reasons, this file does not have general read permission\&.
90f35c2f
FD
298.SH "SEE ALSO"
299.PP
2eeb74d1
TU
300\fBdnssec-keygen\fR(8),
301\fBdnssec-signzone\fR(8),
90f35c2f 302BIND 9 Administrator Reference Manual,
bbbf2e27 303RFC 4034,
2eeb74d1 304The PKCS#11 URI Scheme (draft\-pechanec\-pkcs11uri\-13)\&.
90f35c2f
FD
305.SH "AUTHOR"
306.PP
2eeb74d1 307\fBInternet Systems Consortium, Inc\&.\fR
90f35c2f 308.SH "COPYRIGHT"
2eeb74d1 309.br
b4d3f782 310Copyright \(co 2008-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
90f35c2f 311.br