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 -l, --list
37 Print the list of zones that have at least one key stored in the
38 configured KASP db.
39 Config options
41 -c, --config file
42 Use a textual configuration file (default is
43 /etc/knot/knot.conf).
44 -C, --confdb directory
46 Use a binary configuration database directory (default is
47 /var/lib/knot/confdb). The default configuration database, if
48 exists, has a preference to the default configuration file.
49 -d, --dir path
51 Use specified KASP database path and default configuration.
52 NOTE:
54 Keymgr runs with the same user privileges as configured for knotd.
55 For example, if keymgr is run as root, but the configured user is
56 knot, it won't be able to read files (PEM files, KASP db, ...) read‐
57 able only by root.
58 Commands
60 list [timestamp_format]
61 Prints the list of key IDs and parameters of keys belonging to
62 the zone.
63 generate [arguments...]
65 Generates new DNSSEC key and stores it in KASP database. Prints
66 the key ID. This action takes some number of arguments (see be‐
67 low). Values for unspecified arguments are taken from corre‐
68 sponding policy (if -c or -C options used) or from Knot policy
69 defaults.
70 import-bind BIND_key_file
72 Imports a BIND-style key into KASP database (converting it to
73 PEM format). Takes one argument: path to BIND key file (private
74 or public, but both MUST exist).
75 import-pub BIND_pubkey_file
77 Imports a public key into KASP database. This key won't be
78 rollovered nor used for signing. Takes one argument: path to
79 BIND public key file.
80 import-pem PEM_file [arguments...]
82 Imports a DNSSEC key from PEM file. The key parameters (same as
83 for the generate action) need to be specified (mainly algorithm,
84 timers...) because they are not contained in the PEM format.
85 import-pkcs11 key_id [arguments...]
87 Imports a DNSSEC key from PKCS #11 storage. The key parameters
88 (same as for the generate action) need to be specified (mainly
89 algorithm, timers...) because they are not available. In fact,
90 no key data is imported, only KASP database metadata is created.
91 nsec3-salt [new_salt]
93 Prints the current NSEC3 salt used for signing. If new_salt is
94 specified, the salt is overwritten. The salt is printed and ex‐
95 pected in hexadecimal, or dash if empty.
96 local-serial [new_serial]
98 Print SOA serial stored in KASP database when using on-secondary
99 DNSSEC signing. If new_serial is specified, the serial is over‐
100 written. After updating the serial, expire the zone (zone-purge
101 +expire +zonefile +journal) if the server is running, or remove
102 corresponding zone file and journal contents if the server is
103 stopped.
104 set key_spec [arguments...]
106 Changes a timing argument (or ksk/zsk) of an existing key to a
107 new value. Key_spec is either the key tag or a prefix of the key
108 ID, with an optional [id=|keytag=] prefix; arguments are like
109 for generate, but just the related ones.
110 ds [key_spec]
112 Generate DS record (all digest algorithms together) for speci‐
113 fied key. Key_spec is like for set, if unspecified, all KSKs are
114 used.
115 dnskey [key_spec]
117 Generate DNSKEY record for specified key. Key_spec is like for
118 ds, if unspecified, all KSKs are used.
119 delete key_spec
121 Remove the specified key from zone. If the key was not shared,
122 it is also deleted from keystore.
123 share key_ID zone_from
125 Import a key (specified by full key ID) from another zone as
126 shared. After this, the key is owned by both zones equally.
127 Commands related to Offline KSK feature
129 pregenerate [timestamp-from] timestamp-to
130 Pre-generate ZSKs for use with offline KSK, for the specified
131 period starting from now or specified time.
132 show-offline timestamp-from [timestamp-to]
134 Print pre-generated offline key-related records for specified
135 time interval. If timestamp_to is omitted, it will be to infin‐
136 ity.
137 del-offline timestamp-from timestamp-to
139 Delete pre-generated offline key-related records in specified
140 time interval.
141 del-all-old
143 Delete old keys that are in state 'removed'.
144 generate-ksr timestamp-from timestamp-to
146 Print to stdout KeySigningRequest based on pre-generated ZSKs
147 for specified period.
148 sign-ksr ksr_file
150 Read KeySigingRequest from a text file, sign it using local key‐
151 set and print SignedKeyResponse to stdout.
152 validate-skr skr_file
154 Read SignedKeyResponse from a text file and validate the RRSIGs
155 in it if not corrupt.
156 import-skr skr_file
158 Read SignedKeyResponse from a text file and import the signa‐
159 tures for later use in zone. If some signatures have already
160 been imported, they will be deleted for the period from begin‐
161 ning of the SKR to infinity.
162 Generate arguments
164 Arguments are separated by space, each of them is in format
165 'name=value'.
166 algorithm
168 Either an algorithm number (e.g. 14), or text name without
169 dashes (e.g. ECDSAP384SHA384).
170 size Key length in bits.
172 ksk If set to yes, the key will be used for signing DNSKEY rrset.
174 The generated key will also have the Secure Entry Point flag set
175 to 1.
176 zsk If set to yes, the key will be used for signing zone (except
178 DNSKEY rrset). This flag can be set concurrently with the ksk
179 flag.
180 sep Overrides the standard setting of the Secure Entry Point flag.
182 The following arguments are timestamps of key lifetime (see DNSSEC Key
184 states):
185 pre_active
187 Key started to be used for signing, not published (only for al‐
188 gorithm rollover).
189 publish
191 Key published.
192 ready Key used for signing and submitted to the parent zone (only for
194 KSK).
195 active Key used for signing.
197 retire_active
199 Key still used for signing, but another key is active (only for
200 KSK or algorithm rollover).
201 retire Key still published, but no longer used for signing.
203 post_active
205 Key no longer published, but still used for signing (only for
206 algorithm rollover).
207 revoke Key revoked according to RFC 5011 trust anchor roll-over.
209 remove Key deleted.
211 Timestamps
213 0 Zero timestamp means infinite future.
214 UNIX_time
216 Positive number of seconds since 1970 UTC.
217 YYYYMMDDHHMMSS
219 Date and time in this format without any punctuation.
220 relative_timestamp
222 A sign character (+, -), a number, and an optional time unit (y,
223 mo, d, h, mi, s). The default unit is one second. E.g. +1mi,
224 -2mo.
225 Output timestamp formats
227 (none) The timestamps are printed as UNIX timestamp.
228 human The timestamps are printed relatively to now using time units
230 (e.g. -2y5mo, +1h13s).
231 iso The timestamps are printed in the ISO8601 format (e.g.
233 2016-12-31T23:59:00).
234
236 Exit status of 0 means successful operation. Any other exit status in‐
237 dicates an error.
238
240 1. Generate new TSIG key:
241 $ keymgr -t my_name hmac-sha384
243 2. Generate new DNSSEC key:
245 $ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \
247 ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y
248 3. Import a DNSSEC key from BIND:
250 $ keymgr example.com. import-bind ~/bind/Kharbinge4d5.+007+63089.key
252 4. Configure key timing:
254 $ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
256 5. Share a KSK from another zone:
258 $ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another-zone.com.
260
262 RFC 6781 - DNSSEC Operational Practices. RFC 7583 - DNSSEC Key
263 Rollover Timing Considerations.
264 knot.conf(5), knotc(8), knotd(8).
266
268 CZ.NIC Labs <https://www.knot-dns.cz>
269
271 Copyright 2010–2021, CZ.NIC, z.s.p.o.
2723.0.6 2021-05-12 KEYMGR(8)