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