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

3 4
keymgr – Key management utility
===============================
5 6 7 8

Synopsis
--------

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 38 39
  bit length of the key by number (default: optimal length given by algorithm).

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

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

43 44 45 46
**-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.
47

48
**-d**, **--dir** *path*
49
  Use specified KASP database path and default configuration.
50

51 52
Commands
........
53

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

57 58 59 60 61 62 63 64 65
**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).

66
**import-pem** *PEM_file* [*arguments*...]
67 68
  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.
69

Libor Peltan's avatar
Libor Peltan committed
70
**set** *key_spec* [*arguments*...]
71 72
  Changes a timing argument of an existing key to a new timestamp. *Key_spec* is either the
  key tag or a prefix of the key ID; *arguments* are like for **generate**, but just the
Libor Peltan's avatar
Libor Peltan committed
73 74
  timing-related ones.

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

79 80 81 82
**dnskey** [*key_spec*]
  Generate DNSKEY record for specified key. *Key_spec*
  is like for **ds**, if unspecified, all KSKs are used.

83 84 85 86 87 88 89
**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.

90 91 92 93 94 95 96 97 98 99 100 101
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**
102
  Either 'true' (KSK will be generated) or 'false' (ZSK will be generated).
103 104 105 106 107 108 109

**created**
  Timestamp of key creation.

**publish**
  Timestamp for key to be published.

110 111 112
**ready**
  Timestamp for key to be pre-activated and submitted (in case of KSK).

113 114 115 116 117 118 119 120 121 122 123 124
**active**
  Timestamp for key to be activated.

**retire**
  Timestamp for key to be de-activated.

**remove**
  Timestamp for key ot be deleted.

Timestamps
..........

125 126 127
0
  Zero timestamp means infinite future.

128
*UNIX_time*
129
  Positive number of seconds since 1970 UTC.
130 131 132 133 134

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

*relative_timestamp*
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
  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).
150 151 152 153

Examples
--------

154
1. Generate new TSIG key::
155

156
    $ keymgr -t my_name hmac-sha384
157

158
2. Generate new DNSSEC key::
159

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

163 164 165 166
3. Import a DNSSEC key from BIND::

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

167 168
4. Configure key timing::

169
    $ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
170 171 172

5. Share a KSK from another zone::

173
    $ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9
174

175 176 177 178
See Also
--------

:rfc:`6781` - DNSSEC Operational Practices.
179
:rfc:`7583` - DNSSEC Key Rollover Timing Considerations.
180 181 182 183

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