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