1KEYMGR(8)                          Knot DNS                          KEYMGR(8)
2
3
4

NAME

6       keymgr - Knot DNS key management utility
7

SYNOPSIS

9       keymgr basic_option [parameters...]
10
11       keymgr [config_option config_storage] zone command argument...
12

DESCRIPTION

14       The keymgr utility serves for manual key management in Knot DNS server.
15
16       Functions  for  DNSSEC keys and KASP (Key And Signature Policy) manage‐
17       ment are provided.
18
19       The DNSSEC and KASP configuration is stored in a so called  KASP  data‐
20       base.  The database is backed by LMDB.
21
22   Basic options
23       -h, --help
24              Print the program help.
25
26       -V, --version
27              Print the program version.
28
29       -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
36       -l, --list
37              Print the list of zones that have at least one key stored in the
38              configured KASP db.
39
40   Config options
41       -c, --config file
42              Use    a    textual    configuration    file     (default     is
43              /etc/knot/knot.conf).
44
45       -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
50       -d, --dir path
51              Use specified KASP database path and default configuration.
52
53       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
59   Commands
60       list [timestamp_format]
61              Prints the list of key IDs and parameters of keys  belonging  to
62              the zone.
63
64       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
71       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
76       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
81       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
86       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
92       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
97       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
105       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
111       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
116       dnskey [key_spec]
117              Generate DNSKEY record for specified key. Key_spec is  like  for
118              ds, if unspecified, all KSKs are used.
119
120       delete key_spec
121              Remove  the  specified key from zone. If the key was not shared,
122              it is also deleted from keystore.
123
124       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
128   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
133       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
138       del-offline timestamp-from timestamp-to
139              Delete pre-generated offline key-related  records  in  specified
140              time interval.
141
142       del-all-old
143              Delete old keys that are in state 'removed'.
144
145       generate-ksr timestamp-from timestamp-to
146              Print  to  stdout  KeySigningRequest based on pre-generated ZSKs
147              for specified period.
148
149       sign-ksr ksr_file
150              Read KeySigingRequest from a text file, sign it using local key‐
151              set and print SignedKeyResponse to stdout.
152
153       validate-skr skr_file
154              Read  SignedKeyResponse from a text file and validate the RRSIGs
155              in it if not corrupt.
156
157       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
163   Generate arguments
164       Arguments   are   separated  by  space,  each  of  them  is  in  format
165       'name=value'.
166
167       algorithm
168              Either an algorithm number  (e.g.  14),  or  text  name  without
169              dashes (e.g. ECDSAP384SHA384).
170
171       size   Key length in bits.
172
173       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
177       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
181       sep    Overrides the standard setting of the Secure Entry Point flag.
182
183       The  following arguments are timestamps of key lifetime (see DNSSEC Key
184       states):
185
186       pre_active
187              Key started to be used for signing, not published (only for  al‐
188              gorithm rollover).
189
190       publish
191              Key published.
192
193       ready  Key  used for signing and submitted to the parent zone (only for
194              KSK).
195
196       active Key used for signing.
197
198       retire_active
199              Key still used for signing, but another key is active (only  for
200              KSK or algorithm rollover).
201
202       retire Key still published, but no longer used for signing.
203
204       post_active
205              Key  no  longer  published, but still used for signing (only for
206              algorithm rollover).
207
208       revoke Key revoked according to RFC 5011 trust anchor roll-over.
209
210       remove Key deleted.
211
212   Timestamps
213       0      Zero timestamp means infinite future.
214
215       UNIX_time
216              Positive number of seconds since 1970 UTC.
217
218       YYYYMMDDHHMMSS
219              Date and time in this format without any punctuation.
220
221       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
226   Output timestamp formats
227       (none) The timestamps are printed as UNIX timestamp.
228
229       human  The timestamps are printed relatively to now  using  time  units
230              (e.g. -2y5mo, +1h13s).
231
232       iso    The   timestamps   are  printed  in  the  ISO8601  format  (e.g.
233              2016-12-31T23:59:00).
234

EXIT VALUES

236       Exit status of 0 means successful operation. Any other exit status  in‐
237       dicates an error.
238

EXAMPLES

240       1. Generate new TSIG key:
241
242             $ keymgr -t my_name hmac-sha384
243
244       2. Generate new DNSSEC key:
245
246             $ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \
247               ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y
248
249       3. Import a DNSSEC key from BIND:
250
251             $ keymgr example.com. import-bind ~/bind/Kharbinge4d5.+007+63089.key
252
253       4. Configure key timing:
254
255             $ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
256
257       5. Share a KSK from another zone:
258
259             $ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another-zone.com.
260

SEE ALSO

262       RFC  6781  -  DNSSEC  Operational  Practices.   RFC  7583  - DNSSEC Key
263       Rollover Timing Considerations.
264
265       knot.conf(5), knotc(8), knotd(8).
266

AUTHOR

268       CZ.NIC Labs <https://www.knot-dns.cz>
269
271       Copyright 2010–2021, CZ.NIC, z.s.p.o.
272
273
274
275
2763.0.6                             2021-05-12                         KEYMGR(8)
Impressum