1DNSSEC-KEYGEN(1)                    BIND 9                    DNSSEC-KEYGEN(1)
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

OPTIONS

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
33       -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
41              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
46              This  parameter  must  be specified except when using the -S op‐
47              tion, which copies the algorithm from the predecessor key.
48
49              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
53       -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
60              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
66       -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
74       -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
79       -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
86       -E engine
87              This option specifies the cryptographic hardware  to  use,  when
88              applicable.
89
90              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
94       -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
99       -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
102       -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
108       -h     This  option prints a short summary of the options and arguments
109              to dnssec-keygen.
110
111       -K directory
112              This option sets the directory in which the key files are to  be
113              written.
114
115       -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
121              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
125       -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
133       -l file
134              This option  provides  a  configuration  file  that  contains  a
135              dnssec-policy statement (matching the policy set with -k).
136
137       -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
145       -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
151       -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
161       -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
168       -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
173       -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
179       -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
185       -V     This option prints version information.
186
187       -v level
188              This option sets the debugging level.
189

TIMING OPTIONS

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
196       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
203       To unset a date, use none, never, or unset.
204
205       -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
211              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
216       -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
224       -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
229       -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
234       -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
239              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
243       -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
252              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
256              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

GENERATED KEYS

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
266nnnn is the key name.
267
268aaa is the numeric representation of the algorithm.
269
270iiiii is the key identifier (or footprint).
271
272       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
276       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
281       The .private file contains algorithm-specific fields. For obvious secu‐
282       rity reasons, this file does not have general read permission.
283

EXAMPLE

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

SEE ALSO

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

AUTHOR

306       Internet Systems Consortium
307
309       2023, Internet Systems Consortium
310
311
312
313
3149.18.20                                                       DNSSEC-KEYGEN(1)
Impressum