Adding upstream version 3.2.6.upstream/3.2.6upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 364 insertions, 0 deletions

diff --git a/doc/man/keymgr.8in b/doc/man/keymgr.8in
new file mode 100644
index 0000000..399ece8
--- /dev/null
+++ b/doc/man/keymgr.8in
@@ -0,0 +1,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.
+.