diff options
Diffstat (limited to 'doc/man/keymgr.8')
| -rw-r--r-- | doc/man/keymgr.8 | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/doc/man/keymgr.8 b/doc/man/keymgr.8 new file mode 100644 index 0000000..a963df3 --- /dev/null +++ b/doc/man/keymgr.8 @@ -0,0 +1,390 @@ +.\" 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" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +keymgr \- Knot DNS key management utility +.SH SYNOPSIS +.sp +\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP \fIcommand\fP +.sp +\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIkeystore_id\fP \fIcommand\fP +.sp +\fBkeymgr\fP [\fIconfig_option\fP] [\-j] \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 Parameters +.INDENT 0.0 +.TP +.B \fIzone_name\fP +Name of the zone the command is executed for. +.UNINDENT +.SS Config options +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB/usr/local/etc/knot/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/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 for the given name. Optionally the key algorithm can +be specified by its \fI\%name\fP (default: hmac\-sha256) and +a bit length of the key (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. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Keymgr runs with the same user privileges as configured for \fI\%knotd\fP\&. +For example, if keymgr is run as \fBroot\fP, but the configured \fI\%user\fP +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 Keystore commands +.INDENT 0.0 +.TP +\fBkeystore\-test\fP +Conduct some tests on the specified keystore. For each algorithm, key generation, +import, removal, and use (signing and verification) are tested. +Use a configured \fIkeystore_id\fP or \fB\-\fP for the default. +.TP +\fBkeystore\-bench\fP [\fInum_threads\fP] +Conduct a signing benchmark on the specified keystore. +Random blocks of data are signed by the selected number of threads +(default is 1) in a loop, and the average number of signing operations per +second for each algorithm is returned. +Use a configured \fIkeystore_id\fP or \fB\-\fP for the default. +.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 \fI\%algorithm name\fP +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 \fI\%DNSSEC key states\fP): +.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 +.B 0 +Zero timestamp means infinite future. +.TP +.B \fIUNIX_time\fP +Positive number of seconds since 1970 UTC. +.TP +.B \fIYYYYMMDDHHMMSS\fP +Date and time in this format without any punctuation. +.TP +.B \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 +.B (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–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. |