man_keymgr.rst 7.38 KB
Newer Older
1 2
.. highlight:: console

Daniel Salzman's avatar
Daniel Salzman committed
3 4
keymgr – Key management utility
===============================
5 6 7 8

Synopsis
--------

Daniel Salzman's avatar
Daniel Salzman committed
9
:program:`keymgr` *basic_option* [*parameters*...]
10

11
:program:`keymgr` [*config_option* *config_storage*] *zone* *command* *argument*...
12 13 14 15

Description
-----------

16
The :program:`keymgr` utility serves for manual key management in Knot DNS server.
17 18 19 20 21

Functions for DNSSEC keys and KASP (Key And Signature Policy)
management are provided.

The DNSSEC and KASP configuration is stored in a so called KASP database.
Daniel Salzman's avatar
Daniel Salzman committed
22
The database is backed by LMDB.
23 24

Basic options
25
.............
26

27
**-h**, **--help**
28 29
  Print the program help.

30
**-V**, **--version**
Libor Peltan's avatar
Libor Peltan committed
31 32
  Print the program version.

33 34
**-t**, **--tsig** *tsig_name* [*tsig_algorithm*] [*tsig_bits*]
  Generates a TSIG key. TSIG algorithm can be specified by string (default: hmac-sha256),
35 36 37
  bit length of the key by number (default: optimal length given by algorithm). The generated 
  TSIG key is only displayed on `stdout`: the command does not create a file, nor include the
  key in a keystore.
38 39 40 41

Config options
..............

42 43
**-c**, **--config** *file*
  Use a textual configuration file (default is :file:`@config_dir@/knot.conf`).
44

45 46 47 48
**-C**, **--confdb** *directory*
  Use a binary configuration database directory (default is :file:`@storage_dir@/confdb`).
  The default configuration database, if exists, has a preference to the default
  configuration file.
49

50
**-d**, **--dir** *path*
51
  Use specified KASP database path and default configuration.
52

53 54
Commands
........
55

56
**list** [*timestamp_format*]
Libor Peltan's avatar
Libor Peltan committed
57 58
  Prints the list of key IDs and parameters of keys belonging to the zone.

59 60 61 62 63 64 65 66 67
**generate** [*arguments*...]
  Generates new DNSSEC key and stores it in KASP database. Prints the key ID.
  This action takes some number of arguments (see below). Values for unspecified arguments are taken
  from corresponding policy (if *-c* or *-C* options used) or from Knot policy defaults.

**import-bind** *BIND_key_file*
  Imports a BIND-style key into KASP database (converting it to PEM format).
  Takes one argument: path to BIND key file (private or public, but both MUST exist).

68 69 70 71
**import-pub** *BIND_pubkey_file*
  Imports a public key into KASP database. This key won't be rollovered nor used for signing.
  Takes one argument: path to BIND public key file.

72
**import-pem** *PEM_file* [*arguments*...]
73 74
  Imports a DNSSEC key from PEM file. The key parameters (same as for the generate action) need to be
  specified (mainly algorithm, timers...) because they are not contained in the PEM format.
75

76 77 78 79 80
**import-pkcs11** *key_id* [*arguments*...]
  Imports a DNSSEC key from PKCS #11 storage. The key parameters (same as for the generate action) need to be
  specified (mainly algorithm, timers...) because they are not available. In fact, no key
  data is imported, only KASP database metadata is created.

81 82 83 84
**nsec3-salt** [*new_salt*]
  Prints the current NSEC3 salt used for signing. If *new_salt* is specified, the salt is overwritten.
  The salt is printed and expected in hexadecimal, or dash if empty.

Libor Peltan's avatar
Libor Peltan committed
85
**set** *key_spec* [*arguments*...]
86 87
  Changes a timing argument (or ksk/zsk) of an existing key to a new value. *Key_spec* is either the
  key tag or a prefix of the key ID; *arguments* are like for **generate**, but just the related ones.
Libor Peltan's avatar
Libor Peltan committed
88

89
**ds** [*key_spec*]
90
  Generate DS record (all digest algorithms together) for specified key. *Key_spec*
91
  is like for **set**, if unspecified, all KSKs are used.
Libor Peltan's avatar
Libor Peltan committed
92

93 94 95 96
**dnskey** [*key_spec*]
  Generate DNSKEY record for specified key. *Key_spec*
  is like for **ds**, if unspecified, all KSKs are used.

97 98 99 100 101 102 103
**delete** *key_spec*
  Remove the specified key from zone. If the key was not shared, it is also deleted from keystore.

**share** *key_ID*
  Import a key (specified by full key ID) from another zone as shared. After this, the key is
  owned by both zones equally.

104 105 106
Commands related to Offline KSK feature
.......................................

107
**pregenerate** *timestamp*
108 109
  Pre-generate ZSKs for use with offline KSK, for the specified period starting from now.

110 111
**show-offline** *timestamp*
  Print pre-generated offline key-related records for specified timestamp.
112

113 114
**del-offline** *timestamp-from* *timestamp-to*
  Delete pre-generated offline key-related records in specified time interval.
115

116 117 118
**del-all-old**
  Delete old keys that are in state 'removed'.

119
**generate-ksr** *timestamp*
120 121 122 123 124 125 126 127 128
  Print to stdout KeySigningRequest based on pre-generated ZSKs for specified period.

**sign-ksr** *ksr_file*
  Read KeySigingRequest from a text file, sign it using local keyset and print SignedKeyResponse to stdout.

**import-skr** *skr_file*
  Read SignedKeyResponse from a text file and import the signatures for later use in zone. (The signatures
  are not at all checked at import time, but they will be ignored at signing time if invalid.)

129 130 131 132 133 134 135 136 137 138 139 140
Generate arguments
..................

Arguments are separated by space, each of them is in format 'name=value'.

**algorithm**
  Either an algorithm number (e.g. 14), or text name without dashes (e.g. ECDSAP384SHA384).

**size**
  Key length in bits.

**ksk**
141 142
  If set to **yes**, the key will be used for signing DNSKEY rrset. The generated key will also
  have the Secure Entry Point flag set to 1.
Libor Peltan's avatar
Libor Peltan committed
143 144

**zsk**
145
  If set to **yes**, the key will be used for signing zone (except DNSKEY rrset). This flag can
Libor Peltan's avatar
Libor Peltan committed
146
  be set concurrently with the **ksk** flag.
147

148 149 150
**sep**
  Overrides the standard setting of the Secure Entry Point flag for the generated key.

151 152
The following arguments are timestamps of key lifetime:

153
**created**
154 155 156 157
  Key created.

**pre_active**
  Key started to be used for signing, not published (only for algorithm rollover).
158 159

**publish**
160
  Key published.
161

Libor Peltan's avatar
Libor Peltan committed
162
**ready**
163
  Key used for signing and submitted to the parent zone (only for KSK).
Libor Peltan's avatar
Libor Peltan committed
164

165
**active**
166 167 168 169 170 171 172
  Key used for signing.

**post_active**
  Key still used for singing, but another key is active (only for KSK).

**retire_active**
  Key no longer published, but still used for signing (only for algorithm rollover).
173 174

**retire**
175
  Key still published, but no longer used for signing.
176 177

**remove**
178
  Key deleted.
179 180 181 182

Timestamps
..........

Libor Peltan's avatar
Libor Peltan committed
183 184 185
0
  Zero timestamp means infinite future.

186
*UNIX_time*
187
  Positive number of seconds since 1970 UTC.
188 189 190 191 192

*YYYYMMDDHHMMSS*
  Date and time in this format without any punctuation.

*relative_timestamp*
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
  A sign character (**+**, **-**), a number, and an optional time unit
  (**y**, **mo**, **d**, **h**, **mi**, **s**). The default unit is one second.
  E.g. +1mi, -2mo.

Output timestamp formats
........................

(none)
  The timestamps are printed as UNIX timestamp.

**human**
  The timestamps are printed relatively to now using time units (e.g. -2y5mo, +1h13s).

**iso**
  The timestamps are printed in the ISO8601 format (e.g. 2016-12-31T23:59:00).
208 209 210 211

Examples
--------

212
1. Generate new TSIG key::
213

Daniel Salzman's avatar
Daniel Salzman committed
214
    $ keymgr -t my_name hmac-sha384
215

216
2. Generate new DNSSEC key::
217

218
    $ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \
219
      ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y
220

221 222 223 224
3. Import a DNSSEC key from BIND::

    $ keymgr example.com. import-bind ~/bind/Kharbinge4d5.+007+63089.key

225 226
4. Configure key timing::

227
    $ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
228 229 230

5. Share a KSK from another zone::

231
    $ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9
232

233 234 235 236
See Also
--------

:rfc:`6781` - DNSSEC Operational Practices.
Libor Peltan's avatar
Libor Peltan committed
237
:rfc:`7583` - DNSSEC Key Rollover Timing Considerations.
238 239 240 241

:manpage:`knot.conf(5)`,
:manpage:`knotc(8)`,
:manpage:`knotd(8)`.