1KEYMGR(8) Knot DNS KEYMGR(8)
2
6 keymgr - Knot DNS key management utility
7
9 keymgr [config_option config_argument] [option...] zone_name command
10 argument...
11 keymgr [config_option config_argument] -l
13 keymgr -t parameter...
15
17 The keymgr utility serves for manual key management in Knot DNS server.
18 Functions for DNSSEC keys and KASP (Key And Signature Policy) manage‐
20 ment are provided.
21 The DNSSEC and KASP configuration is stored in a so called KASP data‐
23 base. The database is backed by LMDB.
24 Config options
26 -c, --config file
27 Use a textual configuration file (default is
28 /etc/knot/knot.conf).
29 -C, --confdb directory
31 Use a binary configuration database directory (default is
32 /var/lib/knot/confdb). The default configuration database, if
33 exists, has a preference to the default configuration file.
34 -D, --dir path
36 Use specified KASP database path and default configuration.
37 Options
39 -t, --tsig tsig_name [tsig_algorithm [tsig_bits]]
40 Generates a TSIG key. TSIG algorithm can be specified by string
41 (default: hmac-sha256), bit length of the key by number (de‐
42 fault: optimal length given by algorithm). The generated TSIG
43 key is only displayed on stdout: the command does not create a
44 file, nor include the key in a keystore.
45 -e, --extended
47 Extended output (listing of keys with full description).
48 -j, --json
50 Print the zones or keys in JSON format.
51 -l, --list
53 Print the list of zones that have at least one key stored in the
54 configured KASP database.
55 -x, --mono
57 Don't generate colorized output.
58 -X, --color
60 Force colorized output in the normal mode.
61 -h, --help
63 Print the program help.
64 -V, --version
66 Print the program version.
67 NOTE:
69 Keymgr runs with the same user privileges as configured for knotd.
70 For example, if keymgr is run as root, but the configured user is
71 knot, it won't be able to read files (PEM files, KASP database, ...)
72 readable only by root.
73 Commands
75 list [timestamp_format]
76 Prints the list of key IDs and parameters of keys belonging to
77 the zone.
78 generate [arguments...]
80 Generates new DNSSEC key and stores it in KASP database. Prints
81 the key ID. This action takes some number of arguments (see be‐
82 low). Values for unspecified arguments are taken from corre‐
83 sponding policy (if -c or -C options used) or from Knot policy
84 defaults.
85 import-bind BIND_key_file
87 Imports a BIND-style key into KASP database (converting it to
88 PEM format). Takes one argument: path to BIND key file (private
89 or public, but both MUST exist).
90 import-pub BIND_pubkey_file
92 Imports a public key into KASP database. This key won't be
93 rolled over nor used for signing. Takes one argument: path to
94 BIND public key file.
95 import-pem PEM_file [arguments...]
97 Imports a DNSSEC key from PEM file. The key parameters (same as
98 for the generate action) need to be specified (mainly algorithm,
99 timers...) because they are not contained in the PEM format.
100 import-pkcs11 key_id [arguments...]
102 Imports a DNSSEC key from PKCS #11 storage. The key parameters
103 (same as for the generate action) need to be specified (mainly
104 algorithm, timers...) because they are not available. In fact,
105 no key data is imported, only KASP database metadata is created.
106 nsec3-salt [new_salt]
108 Prints the current NSEC3 salt used for signing. If new_salt is
109 specified, the salt is overwritten. The salt is printed and ex‐
110 pected in hexadecimal, or dash if empty.
111 local-serial [new_serial]
113 Print SOA serial stored in KASP database when using on-secondary
114 DNSSEC signing. If new_serial is specified, the serial is over‐
115 written. After updating the serial, expire the zone (zone-purge
116 +expire +zonefile +journal) if the server is running, or remove
117 corresponding zone file and journal contents if the server is
118 stopped.
119 master-serial [new_serial]
121 Print SOA serial of the remote master stored in KASP database
122 when using on-secondary DNSSEC signing. If new_serial is speci‐
123 fied, the serial is overwritten (not recommended).
124 set key_spec [arguments...]
126 Changes a timing argument (or ksk/zsk) of an existing key to a
127 new value. Key_spec is either the key tag or a prefix of the key
128 ID, with an optional [id=|keytag=] prefix; arguments are like
129 for generate, but just the related ones.
130 ds [key_spec]
132 Generate DS record (all digest algorithms together) for speci‐
133 fied key. Key_spec is like for set, if unspecified, all KSKs are
134 used.
135 dnskey [key_spec]
137 Generate DNSKEY record for specified key. Key_spec is like for
138 ds, if unspecified, all KSKs are used.
139 delete key_spec
141 Remove the specified key from zone. If the key was not shared,
142 it is also deleted from keystore.
143 share key_ID zone_from
145 Import a key (specified by full key ID) from another zone as
146 shared. After this, the key is owned by both zones equally.
147 Commands related to Offline KSK feature
149 pregenerate [timestamp-from] timestamp-to
150 Pre-generate ZSKs for use with offline KSK, for the specified
151 period starting from now or specified time. This function also
152 applies to non-offline KSK keys.
153 show-offline [timestamp-from] [timestamp-to]
155 Print pre-generated offline key-related records for specified
156 time interval. If timestamp_to is omitted, it will be to infin‐
157 ity. If timestamp-from is omitted, it will start from the begin‐
158 ning.
159 del-offline timestamp-from timestamp-to
161 Delete pre-generated offline key-related records in specified
162 time interval.
163 del-all-old
165 Delete old keys that are in state 'removed'. This function also
166 applies to non-offline KSK keys.
167 generate-ksr [timestamp-from] timestamp-to
169 Print to stdout KeySigningRequest based on pre-generated ZSKs
170 for specified time period. If timestamp-from is omitted, time‐
171 stamp of the last offline records set is used or now if no
172 records available.
173 sign-ksr ksr_file
175 Read KeySigningRequest from a text file, sign it using local
176 keyset and print SignedKeyResponse to stdout.
177 validate-skr skr_file
179 Read SignedKeyResponse from a text file and validate the RRSIGs
180 in it if not corrupt.
181 import-skr skr_file
183 Read SignedKeyResponse from a text file and import the signa‐
184 tures for later use in zone. If some signatures have already
185 been imported, they will be deleted for the period from begin‐
186 ning of the SKR to infinity.
187 Generate arguments
189 Arguments are separated by space, each of them is in format
190 'name=value'.
191 algorithm
193 Either an algorithm number (e.g. 14), or text name without
194 dashes (e.g. ECDSAP384SHA384).
195 size Key length in bits.
197 ksk If set to yes, the key will be used for signing DNSKEY rrset.
199 The generated key will also have the Secure Entry Point flag set
200 to 1.
201 zsk If set to yes, the key will be used for signing zone (except
203 DNSKEY rrset). This flag can be set concurrently with the ksk
204 flag.
205 sep Overrides the standard setting of the Secure Entry Point flag.
207 The following arguments are timestamps of key lifetime (see DNSSEC Key
209 states):
210 pre_active
212 Key started to be used for signing, not published (only for al‐
213 gorithm rollover).
214 publish
216 Key published.
217 ready Key is waiting for submission (only for KSK).
219 active Key used for signing.
221 retire_active
223 Key still used for signing, but another key is active (only for
224 KSK or algorithm rollover).
225 retire Key still published, but no longer used for signing.
227 post_active
229 Key no longer published, but still used for signing (only for
230 algorithm rollover).
231 revoke Key revoked according to RFC 5011 trust anchor roll-over.
233 remove Key deleted.
235 Timestamps
237 0 Zero timestamp means infinite future.
238 UNIX_time
240 Positive number of seconds since 1970 UTC.
241 YYYYMMDDHHMMSS
243 Date and time in this format without any punctuation.
244 relative_timestamp
246 A sign character (+, -), a number, and an optional time unit (y,
247 mo, d, h, mi, s). The default unit is one second. E.g. +1mi,
248 -2mo.
249 Output timestamp formats
251 (none) The timestamps are printed as UNIX timestamp.
252 human The timestamps are printed relatively to now using time units
254 (e.g. -2y5mo, +1h13s).
255 iso The timestamps are printed in the ISO8601 format (e.g.
257 2016-12-31T23:59:00).
258
260 Exit status of 0 means successful operation. Any other exit status in‐
261 dicates an error.
262
264 1. Generate new TSIG key:
265 $ keymgr -t my_name hmac-sha384
267 2. Generate new DNSSEC key:
269 $ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \
271 ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y
272 3. Import a DNSSEC key from BIND:
274 $ keymgr example.com. import-bind ~/bind/Kharbinge4d5.+007+63089.key
276 4. Configure key timing:
278 $ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
280 5. Share a KSK from another zone:
282 $ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another-zone.com.
284
286 RFC 6781 - DNSSEC Operational Practices. RFC 7583 - DNSSEC Key
287 Rollover Timing Considerations.
288 knot.conf(5), knotc(8), knotd(8).
290
292 CZ.NIC Labs <https://www.knot-dns.cz>
293
295 Copyright 2010–2022, CZ.NIC, z.s.p.o.
2963.2.4 2022-12-12 KEYMGR(8)