1DNSSEC-KEYGEN(1) BIND 9 DNSSEC-KEYGEN(1)
2
6 dnssec-keygen - DNSSEC key generation tool
7
9 dnssec-keygen [-3] [-A date/offset] [-a algorithm] [-b keysize] [-C]
10 [-c class] [-D date/offset] [-d bits] [-D sync date/offset] [-E engine]
11 [-f flag] [-G] [-g generator] [-h] [-I date/offset] [-i interval] [-K
12 directory] [-k policy] [-L ttl] [-l file] [-n nametype] [-P date/off‐
13 set] [-P sync date/offset] [-p protocol] [-q] [-R date/offset] [-S key]
14 [-s strength] [-T rrtype] [-t type] [-V] [-v level] {name}
15
17 dnssec-keygen generates keys for DNSSEC (Secure DNS), as defined in RFC
18 2535 and RFC 4034. It can also generate keys for use with TSIG (Trans‐
19 action Signatures) as defined in RFC 2845, or TKEY (Transaction Key) as
20 defined in RFC 2930.
21 The name of the key is specified on the command line. For DNSSEC keys,
23 this must match the name of the zone for which the key is being gener‐
24 ated.
25
27 -3 This option uses an NSEC3-capable algorithm to generate a DNSSEC
28 key. If this option is used with an algorithm that has both NSEC
29 and NSEC3 versions, then the NSEC3 version is selected; for ex‐
30 ample, dnssec-keygen -3 -a RSASHA1 specifies the NSEC3RSASHA1
31 algorithm.
32 -a algorithm
34 This option selects the cryptographic algorithm. For DNSSEC
35 keys, the value of algorithm must be one of RSASHA1,
36 NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECD‐
37 SAP384SHA384, ED25519, or ED448. For TKEY, the value must be DH
38 (Diffie-Hellman); specifying this value automatically sets the
39 -T KEY option as well.
40 These values are case-insensitive. In some cases, abbreviations
42 are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384
43 for ECDSAP384SHA384. If RSASHA1 is specified along with the -3
44 option, NSEC3RSASHA1 is used instead.
45 This parameter must be specified except when using the -S op‐
47 tion, which copies the algorithm from the predecessor key.
48 In prior releases, HMAC algorithms could be generated for use as
50 TSIG keys, but that feature was removed in BIND 9.13.0. Use
51 tsig-keygen to generate TSIG keys.
52 -b keysize
54 This option specifies the number of bits in the key. The choice
55 of key size depends on the algorithm used: RSA keys must be be‐
56 tween 1024 and 4096 bits; Diffie-Hellman keys must be between
57 128 and 4096 bits. Elliptic curve algorithms do not need this
58 parameter.
59 If the key size is not specified, some algorithms have pre-de‐
61 fined defaults. For example, RSA keys for use as DNSSEC
62 zone-signing keys have a default size of 1024 bits; RSA keys for
63 use as key-signing keys (KSKs, generated with -f KSK) default to
64 2048 bits.
65 -C This option enables compatibility mode, which generates an
67 old-style key, without any timing metadata. By default,
68 dnssec-keygen includes the key's creation date in the metadata
69 stored with the private key; other dates may be set there as
70 well, including publication date, activation date, etc. Keys
71 that include this data may be incompatible with older versions
72 of BIND; the -C option suppresses them.
73 -c class
75 This option indicates that the DNS record containing the key
76 should have the specified class. If not specified, class IN is
77 used.
78 -d bits
80 This option specifies the key size in bits. For the algorithms
81 RSASHA1, NSEC3RSASA1, RSASHA256, and RSASHA512 the key size must
82 be between 1024 and 4096 bits; DH size is between 128 and 4096
83 bits. This option is ignored for algorithms ECDSAP256SHA256,
84 ECDSAP384SHA384, ED25519, and ED448.
85 -E engine
87 This option specifies the cryptographic hardware to use, when
88 applicable.
89 When BIND 9 is built with OpenSSL, this needs to be set to the
91 OpenSSL engine identifier that drives the cryptographic acceler‐
92 ator or hardware service module (usually pkcs11).
93 -f flag
95 This option sets the specified flag in the flag field of the
96 KEY/DNSKEY record. The only recognized flags are KSK (Key-Sign‐
97 ing Key) and REVOKE.
98 -G This option generates a key, but does not publish it or sign
100 with it. This option is incompatible with -P and -A.
101 -g generator
103 This option indicates the generator to use if generating a
104 Diffie-Hellman key. Allowed values are 2 and 5. If no generator
105 is specified, a known prime from RFC 2539 is used if possible;
106 otherwise the default is 2.
107 -h This option prints a short summary of the options and arguments
109 to dnssec-keygen.
110 -K directory
112 This option sets the directory in which the key files are to be
113 written.
114 -k policy
116 This option creates keys for a specific dnssec-policy. If a pol‐
117 icy uses multiple keys, dnssec-keygen generates multiple keys.
118 This also creates a ".state" file to keep track of the key
119 state.
120 This option creates keys according to the dnssec-policy configu‐
122 ration, hence it cannot be used at the same time as many of the
123 other options that dnssec-keygen provides.
124 -L ttl This option sets the default TTL to use for this key when it is
126 converted into a DNSKEY RR. This is the TTL used when the key is
127 imported into a zone, unless there was already a DNSKEY RRset in
128 place, in which case the existing TTL takes precedence. If this
129 value is not set and there is no existing DNSKEY RRset, the TTL
130 defaults to the SOA TTL. Setting the default TTL to 0 or none is
131 the same as leaving it unset.
132 -l file
134 This option provides a configuration file that contains a
135 dnssec-policy statement (matching the policy set with -k).
136 -n nametype
138 This option specifies the owner type of the key. The value of
139 nametype must either be ZONE (for a DNSSEC zone key
140 (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host
141 (KEY)), USER (for a key associated with a user (KEY)), or OTHER
142 (DNSKEY). These values are case-insensitive. The default is ZONE
143 for DNSKEY generation.
144 -p protocol
146 This option sets the protocol value for the generated key, for
147 use with -T KEY. The protocol is a number between 0 and 255. The
148 default is 3 (DNSSEC). Other possible values for this argument
149 are listed in RFC 2535 and its successors.
150 -q This option sets quiet mode, which suppresses unnecessary out‐
152 put, including progress indication. Without this option, when
153 dnssec-keygen is run interactively to generate an RSA or DSA key
154 pair, it prints a string of symbols to stderr indicating the
155 progress of the key generation. A . indicates that a random num‐
156 ber has been found which passed an initial sieve test; + means a
157 number has passed a single round of the Miller-Rabin primality
158 test; and a space ( ) means that the number has passed all the
159 tests and is a satisfactory key.
160 -S key This option creates a new key which is an explicit successor to
162 an existing key. The name, algorithm, size, and type of the key
163 are set to match the existing key. The activation date of the
164 new key is set to the inactivation date of the existing one. The
165 publication date is set to the activation date minus the prepub‐
166 lication interval, which defaults to 30 days.
167 -s strength
169 This option specifies the strength value of the key. The
170 strength is a number between 0 and 15, and currently has no de‐
171 fined purpose in DNSSEC.
172 -T rrtype
174 This option specifies the resource record type to use for the
175 key. rrtype must be either DNSKEY or KEY. The default is DNSKEY
176 when using a DNSSEC algorithm, but it can be overridden to KEY
177 for use with SIG(0).
178 -t type
180 This option indicates the type of the key for use with -T KEY.
181 type must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The
182 default is AUTHCONF. AUTH refers to the ability to authenticate
183 data, and CONF to the ability to encrypt data.
184 -V This option prints version information.
186 -v level
188 This option sets the debugging level.
189
191 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS (which
192 is the format used inside key files), or 'Day Mon DD HH:MM:SS YYYY' (as
193 printed by dnssec-settime -p), or UNIX epoch time (as printed by
194 dnssec-settime -up), or the literal now.
195 The argument can be followed by + or - and an offset from the given
197 time. The literal now can be omitted before an offset. The offset can
198 be followed by one of the suffixes y, mo, w, d, h, or mi, so that it is
199 computed in years (defined as 365 24-hour days, ignoring leap years),
200 months (defined as 30 24-hour days), weeks, days, hours, or minutes,
201 respectively. Without a suffix, the offset is computed in seconds.
202 To unset a date, use none, never, or unset.
204 -P date/offset
206 This option sets the date on which a key is to be published to
207 the zone. After that date, the key is included in the zone but
208 is not used to sign it. If not set, and if the -G option has not
209 been used, the default is the current date.
210 sync date/offset
212 This option sets the date on which CDS and CDNSKEY
213 records that match this key are to be published to the
214 zone.
215 -A date/offset
217 This option sets the date on which the key is to be activated.
218 After that date, the key is included in the zone and used to
219 sign it. If not set, and if the -G option has not been used, the
220 default is the current date. If set, and -P is not set, the pub‐
221 lication date is set to the activation date minus the prepubli‐
222 cation interval.
223 -R date/offset
225 This option sets the date on which the key is to be revoked. Af‐
226 ter that date, the key is flagged as revoked. It is included in
227 the zone and is used to sign it.
228 -I date/offset
230 This option sets the date on which the key is to be retired. Af‐
231 ter that date, the key is still included in the zone, but it is
232 not used to sign it.
233 -D date/offset
235 This option sets the date on which the key is to be deleted. Af‐
236 ter that date, the key is no longer included in the zone. (How‐
237 ever, it may remain in the key repository.)
238 sync date/offset
240 This option sets the date on which the CDS and CDNSKEY
241 records that match this key are to be deleted.
242 -i interval
244 This option sets the prepublication interval for a key. If set,
245 then the publication and activation dates must be separated by
246 at least this much time. If the activation date is specified but
247 the publication date is not, the publication date defaults to
248 this much time before the activation date; conversely, if the
249 publication date is specified but not the activation date, acti‐
250 vation is set to this much time after publication.
251 If the key is being created as an explicit successor to another
253 key, then the default prepublication interval is 30 days; other‐
254 wise it is zero.
255 As with date offsets, if the argument is followed by one of the
257 suffixes y, mo, w, d, h, or mi, the interval is measured in
258 years, months, weeks, days, hours, or minutes, respectively.
259 Without a suffix, the interval is measured in seconds.
260
262 When dnssec-keygen completes successfully, it prints a string of the
263 form Knnnn.+aaa+iiiii to the standard output. This is an identification
264 string for the key it has generated.
265 • nnnn is the key name.
267 • aaa is the numeric representation of the algorithm.
269 • iiiii is the key identifier (or footprint).
271 dnssec-keygen creates two files, with names based on the printed
273 string. Knnnn.+aaa+iiiii.key contains the public key, and
274 Knnnn.+aaa+iiiii.private contains the private key.
275 The .key file contains a DNSKEY or KEY record. When a zone is being
277 signed by named or dnssec-signzone -S, DNSKEY records are included au‐
278 tomatically. In other cases, the .key file can be inserted into a zone
279 file manually or with an $INCLUDE statement.
280 The .private file contains algorithm-specific fields. For obvious secu‐
282 rity reasons, this file does not have general read permission.
283
285 To generate an ECDSAP256SHA256 zone-signing key for the zone exam‐
286 ple.com, issue the command:
287 dnssec-keygen -a ECDSAP256SHA256 example.com
289 The command prints a string of the form:
291 Kexample.com.+013+26160
293 In this example, dnssec-keygen creates the files Kexam‐
295 ple.com.+013+26160.key and Kexample.com.+013+26160.private.
296 To generate a matching key-signing key, issue the command:
298 dnssec-keygen -a ECDSAP256SHA256 -f KSK example.com
300
302 dnssec-signzone(8), BIND 9 Administrator Reference Manual, RFC 2539,
303 RFC 2845, RFC 4034.
304
306 Internet Systems Consortium
307
309 2023, Internet Systems Consortium
3109.18.11 DNSSEC-KEYGEN(1)