1DNSSEC-KEYGEN(8)                    BIND 9                    DNSSEC-KEYGEN(8)
2
3
4

NAME

6       dnssec-keygen - DNSSEC key generation tool
7

SYNOPSIS

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

DESCRIPTION

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
22       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
26       The  dnssec-keymgr command acts as a wrapper around dnssec-keygen, gen‐
27       erating and updating keys as needed to enforce defined  security  poli‐
28       cies  such  as  key  rollover  scheduling.  Using  dnssec-keymgr may be
29       preferable to direct use of dnssec-keygen.
30

OPTIONS

32       -3     This option uses an NSEC3-capable algorithm to generate a DNSSEC
33              key. If this option is used with an algorithm that has both NSEC
34              and NSEC3 versions, then the NSEC3 version is selected; for  ex‐
35              ample,  dnssec-keygen -3a RSASHA1 specifies the NSEC3RSASHA1 al‐
36              gorithm.
37
38       -a algorithm
39              This option selects  the  cryptographic  algorithm.  For  DNSSEC
40              keys,   the   value   of  algorithm  must  be  one  of  RSASHA1,
41              NSEC3RSASHA1,  RSASHA256,   RSASHA512,   ECDSAP256SHA256,   ECD‐
42              SAP384SHA384,  ED25519, or ED448. For TKEY, the value must be DH
43              (Diffie-Hellman); specifying this value automatically  sets  the
44              -T KEY option as well.
45
46              These  values are case-insensitive. In some cases, abbreviations
47              are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384
48              for  ECDSAP384SHA384.  If RSASHA1 is specified along with the -3
49              option, NSEC3RSASHA1 is used instead.
50
51              This parameter must be specified except when using  the  -S  op‐
52              tion, which copies the algorithm from the predecessor key.
53
54              In prior releases, HMAC algorithms could be generated for use as
55              TSIG keys, but that feature was  removed  in  BIND  9.13.0.  Use
56              tsig-keygen to generate TSIG keys.
57
58       -b keysize
59              This  option specifies the number of bits in the key. The choice
60              of key size depends on the algorithm used: RSA keys must be  be‐
61              tween  1024  and  4096 bits; Diffie-Hellman keys must be between
62              128 and 4096 bits. Elliptic curve algorithms do  not  need  this
63              parameter.
64
65              If  the  key size is not specified, some algorithms have pre-de‐
66              fined  defaults.  For  example,  RSA  keys  for  use  as  DNSSEC
67              zone-signing keys have a default size of 1024 bits; RSA keys for
68              use as key-signing keys (KSKs, generated with -f KSK) default to
69              2048 bits.
70
71       -C     This  option  enables  compatibility  mode,  which  generates an
72              old-style  key,  without  any  timing  metadata.   By   default,
73              dnssec-keygen  includes  the key's creation date in the metadata
74              stored with the private key; other dates may  be  set  there  as
75              well,  including  publication  date,  activation date, etc. Keys
76              that include this data may be incompatible with  older  versions
77              of BIND; the -C option suppresses them.
78
79       -c class
80              This  option  indicates  that  the DNS record containing the key
81              should have the specified class. If not specified, class  IN  is
82              used.
83
84       -d bits
85              This  option  specifies the key size in bits. For the algorithms
86              RSASHA1, NSEC3RSASA1, RSASHA256, and RSASHA512 the key size must
87              be  between  1024 and 4096 bits; DH size is between 128 and 4096
88              bits. This option is  ignored  for  algorithms  ECDSAP256SHA256,
89              ECDSAP384SHA384, ED25519, and ED448.
90
91       -E engine
92              This  option  specifies  the cryptographic hardware to use, when
93              applicable.
94
95              When BIND 9 is built with OpenSSL, this needs to be set  to  the
96              OpenSSL engine identifier that drives the cryptographic acceler‐
97              ator or hardware service module (usually pkcs11). When  BIND  is
98              built with native PKCS#11 cryptography (--enable-native-pkcs11),
99              it defaults to the path of the PKCS#11 provider  library  speci‐
100              fied via --with-pkcs11.
101
102       -f flag
103              This  option  sets  the  specified flag in the flag field of the
104              KEY/DNSKEY record.  The only recognized flags are KSK (Key-Sign‐
105              ing Key) and REVOKE.
106
107       -G     This  option  generates  a  key, but does not publish it or sign
108              with it. This option is incompatible with -P and -A.
109
110       -g generator
111              This option indicates the  generator  to  use  if  generating  a
112              Diffie-Hellman  key. Allowed values are 2 and 5. If no generator
113              is specified, a known prime from RFC 2539 is used  if  possible;
114              otherwise the default is 2.
115
116       -h     This  option prints a short summary of the options and arguments
117              to dnssec-keygen.
118
119       -K directory
120              This option sets the directory in which the key files are to  be
121              written.
122
123       -k policy
124              This option creates keys for a specific dnssec-policy. If a pol‐
125              icy uses multiple keys, dnssec-keygen generates  multiple  keys.
126              This  also  creates  a  ".state"  file  to keep track of the key
127              state.
128
129              This option creates keys according to the dnssec-policy configu‐
130              ration,  hence it cannot be used at the same time as many of the
131              other options that dnssec-keygen provides.
132
133       -L ttl This option sets the default TTL to use for this key when it  is
134              converted into a DNSKEY RR. This is the TTL used when the key is
135              imported into a zone, unless there was already a DNSKEY RRset in
136              place,  in which case the existing TTL takes precedence. If this
137              value is not set and there is no existing DNSKEY RRset, the  TTL
138              defaults to the SOA TTL. Setting the default TTL to 0 or none is
139              the same as leaving it unset.
140
141       -l file
142              This option  provides  a  configuration  file  that  contains  a
143              dnssec-policy statement (matching the policy set with -k).
144
145       -n nametype
146              This  option  specifies  the owner type of the key. The value of
147              nametype  must  either  be  ZONE  (for   a   DNSSEC   zone   key
148              (KEY/DNSKEY)),  HOST or ENTITY (for a key associated with a host
149              (KEY)), USER (for a key associated with a user (KEY)), or  OTHER
150              (DNSKEY). These values are case-insensitive. The default is ZONE
151              for DNSKEY generation.
152
153       -p protocol
154              This option sets the protocol value for the generated  key,  for
155              use with -T KEY. The protocol is a number between 0 and 255. The
156              default is 3 (DNSSEC). Other possible values for  this  argument
157              are listed in RFC 2535 and its successors.
158
159       -q     This  option  sets quiet mode, which suppresses unnecessary out‐
160              put, including progress indication. Without  this  option,  when
161              dnssec-keygen is run interactively to generate an RSA or DSA key
162              pair, it prints a string of symbols  to  stderr  indicating  the
163              progress of the key generation. A . indicates that a random num‐
164              ber has been found which passed an initial sieve test; + means a
165              number  has  passed a single round of the Miller-Rabin primality
166              test; and a space ( ) means that the number has passed  all  the
167              tests and is a satisfactory key.
168
169       -S key This  option creates a new key which is an explicit successor to
170              an existing key.  The name, algorithm, size, and type of the key
171              are  set  to  match the existing key. The activation date of the
172              new key is set to the inactivation date of the existing one. The
173              publication date is set to the activation date minus the prepub‐
174              lication interval, which defaults to 30 days.
175
176       -s strength
177              This option  specifies  the  strength  value  of  the  key.  The
178              strength  is a number between 0 and 15, and currently has no de‐
179              fined purpose in DNSSEC.
180
181       -T rrtype
182              This option specifies the resource record type to  use  for  the
183              key.  rrtype must be either DNSKEY or KEY. The default is DNSKEY
184              when using a DNSSEC algorithm, but it can be overridden  to  KEY
185              for use with SIG(0).
186
187       -t type
188              This  option  indicates the type of the key for use with -T KEY.
189              type must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The
190              default  is AUTHCONF. AUTH refers to the ability to authenticate
191              data, and CONF to the ability to encrypt data.
192
193       -V     This option prints version information.
194
195       -v level
196              This option sets the debugging level.
197

TIMING OPTIONS

199       Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the
200       argument  begins with a + or -, it is interpreted as an offset from the
201       present time. For convenience, if such an offset is followed by one  of
202       the  suffixes  y,  mo,  w,  d, h, or mi, then the offset is computed in
203       years (defined as 365 24-hour days, ignoring leap years),  months  (de‐
204       fined  as  30  24-hour  days),  weeks, days, hours, or minutes, respec‐
205       tively. Without a suffix, the offset is computed in seconds. To explic‐
206       itly prevent a date from being set, use none or never.
207
208       -P date/offset
209              This  option  sets the date on which a key is to be published to
210              the zone. After that date, the key is included in the  zone  but
211              is not used to sign it. If not set, and if the -G option has not
212              been used, the default is the current date.
213
214       -P sync date/offset
215              This option sets the date on which CDS and CDNSKEY records  that
216              match this key are to be published to the zone.
217
218       -A date/offset
219              This  option  sets the date on which the key is to be activated.
220              After that date, the key is included in the  zone  and  used  to
221              sign it. If not set, and if the -G option has not been used, the
222              default is the current date. If set, and -P is not set, the pub‐
223              lication  date is set to the activation date minus the prepubli‐
224              cation interval.
225
226       -R date/offset
227              This option sets the date on which the key is to be revoked. Af‐
228              ter  that date, the key is flagged as revoked. It is included in
229              the zone and is used to sign it.
230
231       -I date/offset
232              This option sets the date on which the key is to be retired. Af‐
233              ter  that date, the key is still included in the zone, but it is
234              not used to sign it.
235
236       -D date/offset
237              This option sets the date on which the key is to be deleted. Af‐
238              ter  that date, the key is no longer included in the zone. (How‐
239              ever, it may remain in the key repository.)
240
241       -D sync date/offset
242              This option sets the date on which the CDS and  CDNSKEY  records
243              that match this key are to be deleted.
244
245       -i interval
246              This  option sets the prepublication interval for a key. If set,
247              then the publication and activation dates must be  separated  by
248              at least this much time. If the activation date is specified but
249              the publication date is not, the publication  date  defaults  to
250              this  much  time  before the activation date; conversely, if the
251              publication date is specified but not the activation date, acti‐
252              vation is set to this much time after publication.
253
254              If  the key is being created as an explicit successor to another
255              key, then the default prepublication interval is 30 days; other‐
256              wise it is zero.
257
258              As  with date offsets, if the argument is followed by one of the
259              suffixes y, mo, w, d, h, or mi,  the  interval  is  measured  in
260              years,  months,  weeks,  days,  hours, or minutes, respectively.
261              Without a suffix, the interval is measured in seconds.
262

GENERATED KEYS

264       When dnssec-keygen completes successfully, it prints a  string  of  the
265       form Knnnn.+aaa+iiiii to the standard output. This is an identification
266       string for the key it has generated.
267
268nnnn is the key name.
269
270aaa is the numeric representation of the algorithm.
271
272iiiii is the key identifier (or footprint).
273
274       dnssec-keygen creates two  files,  with  names  based  on  the  printed
275       string.    Knnnn.+aaa+iiiii.key    contains   the   public   key,   and
276       Knnnn.+aaa+iiiii.private contains the private key.
277
278       The .key file contains a DNSKEY or KEY record. When  a  zone  is  being
279       signed  by named or dnssec-signzone -S, DNSKEY records are included au‐
280       tomatically. In other cases, the .key file can be inserted into a  zone
281       file manually or with an $INCLUDE statement.
282
283       The .private file contains algorithm-specific fields. For obvious secu‐
284       rity reasons, this file does not have general read permission.
285

EXAMPLE

287       To generate an ECDSAP256SHA256 zone-signing  key  for  the  zone  exam‐
288       ple.com, issue the command:
289
290       dnssec-keygen -a ECDSAP256SHA256 example.com
291
292       The command prints a string of the form:
293
294       Kexample.com.+013+26160
295
296       In    this    example,   dnssec-keygen   creates   the   files   Kexam‐
297       ple.com.+013+26160.key and Kexample.com.+013+26160.private.
298
299       To generate a matching key-signing key, issue the command:
300
301       dnssec-keygen -a ECDSAP256SHA256 -f KSK example.com
302

SEE ALSO

304       dnssec-signzone(8), BIND 9 Administrator Reference  Manual,  RFC  2539,
305       RFC 2845, RFC 4034.
306

AUTHOR

308       Internet Systems Consortium
309
311       2021, Internet Systems Consortium
312
313
314
315
3169.16.23-RH                                                    DNSSEC-KEYGEN(8)
Impressum