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