summaryrefslogtreecommitdiffstats
path: root/doc/man/keymgr.8in
blob: 399ece89dba5eace213e8fb6292972cd0872bbc9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "KEYMGR" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS"
.SH NAME
keymgr \- Knot DNS key management utility
.SH SYNOPSIS
.sp
\fBkeymgr\fP [\fIconfig_option\fP \fIconfig_argument\fP] [\fIoption\fP\&...] \fIzone_name\fP \fIcommand\fP \fIargument\fP\&...
.sp
\fBkeymgr\fP [\fIconfig_option\fP \fIconfig_argument\fP] \fB\-l\fP
.sp
\fBkeymgr\fP \fB\-t\fP \fIparameter\fP\&...
.SH DESCRIPTION
.sp
The \fBkeymgr\fP utility serves for manual key management in Knot DNS server.
.sp
Functions for DNSSEC keys and KASP (Key And Signature Policy)
management are provided.
.sp
The DNSSEC and KASP configuration is stored in a so called KASP database.
The database is backed by LMDB.
.SS Config options
.INDENT 0.0
.TP
\fB\-c\fP, \fB\-\-config\fP \fIfile\fP
Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP).
.TP
\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP
Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP).
The default configuration database, if exists, has a preference to the default
configuration file.
.TP
\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP
Use specified KASP database path and default configuration.
.UNINDENT
.SS Options
.INDENT 0.0
.TP
\fB\-t\fP, \fB\-\-tsig\fP \fItsig_name\fP [\fItsig_algorithm\fP [\fItsig_bits\fP]]
Generates a TSIG key. TSIG algorithm can be specified by string (default: hmac\-sha256),
bit length of the key by number (default: optimal length given by algorithm). The generated
TSIG key is only displayed on \fIstdout\fP: the command does not create a file, nor include the
key in a keystore.
.TP
\fB\-e\fP, \fB\-\-extended\fP
Extended output (listing of keys with full description).
.TP
\fB\-j\fP, \fB\-\-json\fP
Print the zones or keys in JSON format.
.TP
\fB\-l\fP, \fB\-\-list\fP
Print the list of zones that have at least one key stored in the configured KASP
database.
.TP
\fB\-x\fP, \fB\-\-mono\fP
Don\(aqt generate colorized output.
.TP
\fB\-X\fP, \fB\-\-color\fP
Force colorized output in the normal mode.
.TP
\fB\-h\fP, \fB\-\-help\fP
Print the program help.
.TP
\fB\-V\fP, \fB\-\-version\fP
Print the program version.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Keymgr runs with the same user privileges as configured for knotd\&.
For example, if keymgr is run as \fBroot\fP, but the configured user
is \fBknot\fP, it won\(aqt be able to read files (PEM files, KASP database, ...) readable
only by \fBroot\fP\&.
.UNINDENT
.UNINDENT
.SS Commands
.INDENT 0.0
.TP
\fBlist\fP [\fItimestamp_format\fP]
Prints the list of key IDs and parameters of keys belonging to the zone.
.TP
\fBgenerate\fP [\fIarguments\fP\&...]
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 \fI\-c\fP or \fI\-C\fP options used) or from Knot policy defaults.
.TP
\fBimport\-bind\fP \fIBIND_key_file\fP
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).
.TP
\fBimport\-pub\fP \fIBIND_pubkey_file\fP
Imports a public key into KASP database. This key won\(aqt be rolled over nor used for signing.
Takes one argument: path to BIND public key file.
.TP
\fBimport\-pem\fP \fIPEM_file\fP [\fIarguments\fP\&...]
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.
.TP
\fBimport\-pkcs11\fP \fIkey_id\fP [\fIarguments\fP\&...]
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.
.TP
\fBnsec3\-salt\fP [\fInew_salt\fP]
Prints the current NSEC3 salt used for signing. If \fInew_salt\fP is specified, the salt is overwritten.
The salt is printed and expected in hexadecimal, or dash if empty.
.TP
\fBlocal\-serial\fP [\fInew_serial\fP]
Print SOA serial stored in KASP database when using on\-secondary DNSSEC signing.
If \fInew_serial\fP is specified, the serial is overwritten. After updating the serial, expire the zone
(\fBzone\-purge +expire +zonefile +journal\fP) if the server is running, or remove corresponding zone file
and journal contents if the server is stopped.
.TP
\fBmaster\-serial\fP [\fInew_serial\fP]
Print SOA serial of the remote master stored in KASP database when using on\-secondary DNSSEC signing.
If \fInew_serial\fP is specified, the serial is overwritten (not recommended).
.TP
\fBset\fP \fIkey_spec\fP [\fIarguments\fP\&...]
Changes a timing argument (or ksk/zsk) of an existing key to a new value. \fIKey_spec\fP is either the
key tag or a prefix of the key ID, with an optional \fI[id=|keytag=]\fP prefix; \fIarguments\fP
are like for \fBgenerate\fP, but just the related ones.
.TP
\fBds\fP [\fIkey_spec\fP]
Generate DS record (all digest algorithms together) for specified key. \fIKey_spec\fP
is like for \fBset\fP, if unspecified, all KSKs are used.
.TP
\fBdnskey\fP [\fIkey_spec\fP]
Generate DNSKEY record for specified key. \fIKey_spec\fP
is like for \fBds\fP, if unspecified, all KSKs are used.
.TP
\fBdelete\fP \fIkey_spec\fP
Remove the specified key from zone. If the key was not shared, it is also deleted from keystore.
.TP
\fBshare\fP \fIkey_ID\fP \fIzone_from\fP
Import a key (specified by full key ID) from another zone as shared. After this, the key is
owned by both zones equally.
.UNINDENT
.SS Commands related to Offline KSK feature
.INDENT 0.0
.TP
\fBpregenerate\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP
Pre\-generate ZSKs for use with offline KSK, for the specified period starting from now or specified time.
This function also applies to non\-offline KSK keys.
.TP
\fBshow\-offline\fP [\fItimestamp\-from\fP] [\fItimestamp\-to\fP]
Print pre\-generated offline key\-related records for specified time interval. If \fItimestamp_to\fP
is omitted, it will be to infinity. If \fItimestamp\-from\fP is omitted, it will start from the
beginning.
.TP
\fBdel\-offline\fP \fItimestamp\-from\fP \fItimestamp\-to\fP
Delete pre\-generated offline key\-related records in specified time interval.
.TP
\fBdel\-all\-old\fP
Delete old keys that are in state \(aqremoved\(aq. This function also applies to
non\-offline KSK keys.
.TP
\fBgenerate\-ksr\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP
Print to stdout KeySigningRequest based on pre\-generated ZSKs for specified time period.
If \fItimestamp\-from\fP is omitted, timestamp of the last offline records set is used
or now if no records available.
.TP
\fBsign\-ksr\fP \fIksr_file\fP
Read KeySigningRequest from a text file, sign it using local keyset and print SignedKeyResponse to stdout.
.TP
\fBvalidate\-skr\fP \fIskr_file\fP
Read SignedKeyResponse from a text file and validate the RRSIGs in it if not corrupt.
.TP
\fBimport\-skr\fP \fIskr_file\fP
Read SignedKeyResponse from a text file and import the signatures for later use in zone. If some
signatures have already been imported, they will be deleted for the period from beginning of the SKR
to infinity.
.UNINDENT
.SS Generate arguments
.sp
Arguments are separated by space, each of them is in format \(aqname=value\(aq.
.INDENT 0.0
.TP
\fBalgorithm\fP
Either an algorithm number (e.g. 14), or text name without dashes (e.g. ECDSAP384SHA384).
.TP
\fBsize\fP
Key length in bits.
.TP
\fBksk\fP
If set to \fByes\fP, the key will be used for signing DNSKEY rrset. The generated key will also
have the Secure Entry Point flag set to 1.
.TP
\fBzsk\fP
If set to \fByes\fP, the key will be used for signing zone (except DNSKEY rrset). This flag can
be set concurrently with the \fBksk\fP flag.
.TP
\fBsep\fP
Overrides the standard setting of the Secure Entry Point flag.
.UNINDENT
.sp
The following arguments are timestamps of key lifetime (see DNSSEC Key states):
.INDENT 0.0
.TP
\fBpre_active\fP
Key started to be used for signing, not published (only for algorithm rollover).
.TP
\fBpublish\fP
Key published.
.TP
\fBready\fP
Key is waiting for submission (only for KSK).
.TP
\fBactive\fP
Key used for signing.
.TP
\fBretire_active\fP
Key still used for signing, but another key is active (only for KSK or algorithm rollover).
.TP
\fBretire\fP
Key still published, but no longer used for signing.
.TP
\fBpost_active\fP
Key no longer published, but still used for signing (only for algorithm rollover).
.TP
\fBrevoke\fP
Key revoked according to \fI\%RFC 5011\fP trust anchor roll\-over.
.TP
\fBremove\fP
Key deleted.
.UNINDENT
.SS Timestamps
.INDENT 0.0
.TP
0
Zero timestamp means infinite future.
.TP
\fIUNIX_time\fP
Positive number of seconds since 1970 UTC.
.TP
\fIYYYYMMDDHHMMSS\fP
Date and time in this format without any punctuation.
.TP
\fIrelative_timestamp\fP
A sign character (\fB+\fP, \fB\-\fP), a number, and an optional time unit
(\fBy\fP, \fBmo\fP, \fBd\fP, \fBh\fP, \fBmi\fP, \fBs\fP). The default unit is one second.
E.g. +1mi, \-2mo.
.UNINDENT
.SS Output timestamp formats
.INDENT 0.0
.TP
(none)
The timestamps are printed as UNIX timestamp.
.TP
\fBhuman\fP
The timestamps are printed relatively to now using time units (e.g. \-2y5mo, +1h13s).
.TP
\fBiso\fP
The timestamps are printed in the ISO8601 format (e.g. 2016\-12\-31T23:59:00).
.UNINDENT
.SH EXIT VALUES
.sp
Exit status of 0 means successful operation. Any other exit status indicates
an error.
.SH EXAMPLES
.INDENT 0.0
.IP 1. 3
Generate new TSIG key:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ keymgr \-t my_name hmac\-sha384
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Generate new DNSSEC key:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \e
  ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Import a DNSSEC key from BIND:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ keymgr example.com. import\-bind ~/bind/Kharbinge4d5.+007+63089.key
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 3
Configure key timing:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 5. 3
Share a KSK from another zone:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another\-zone.com.
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fI\%RFC 6781\fP \- DNSSEC Operational Practices.
\fI\%RFC 7583\fP \- DNSSEC Key Rollover Timing Considerations.
.sp
\fBknot.conf(5)\fP,
\fBknotc(8)\fP,
\fBknotd(8)\fP\&.
.SH AUTHOR
CZ.NIC Labs <https://www.knot-dns.cz>
.SH COPYRIGHT
Copyright 2010–2023, CZ.NIC, z.s.p.o.
.\" Generated by docutils manpage writer.
.