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