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