Adding upstream version 3.3.4.upstream/3.3.4

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

1 files changed, 300 insertions, 0 deletions

diff --git a/doc/man_keymgr.rst b/doc/man_keymgr.rst
new file mode 100644
index 0000000..362790e
--- /dev/null
+++ b/doc/man_keymgr.rst
@@ -0,0 +1,300 @@
+.. highlight:: none
+
+``keymgr`` – Key management utility
+===================================
+
+Synopsis
+--------
+
+:program:`keymgr` [*config_option*] [*options*] *zone_name* *command*
+
+:program:`keymgr` [*config_option*] [-j] **-l**
+
+:program:`keymgr` **-t** *parameter*...
+
+Description
+-----------
+
+The :program:`keymgr` utility serves for manual key management in Knot DNS server.
+
+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.
+The database is backed by LMDB.
+
+Parameters
+..........
+
+*zone_name*
+  Name of the zone the command is executed for.
+
+Config options
+..............
+
+**-c**, **--config** *file*
+  Use a textual configuration file (default is :file:`@config_dir@/knot.conf`).
+
+**-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.
+
+**-D**, **--dir** *path*
+  Use specified KASP database path and default configuration.
+
+Options
+.......
+
+**-t**, **--tsig** *tsig_name* [*tsig_algorithm* [*tsig_bits*]]
+  Generates a TSIG key for the given name. Optionally the key algorithm can
+  be specified by its :ref:`name<key_algorithm>` (default: hmac-sha256) and
+  a bit length of the key (default: optimal length given by algorithm).
+  The generated TSIG key is only displayed on `stdout`:
+  the command does not create a file, nor include the key in a keystore.
+
+**-e**, **--extended**
+  Extended output (listing of keys with full description).
+
+**-j**, **--json**
+  Print the zones or keys in JSON format.
+
+**-l**, **--list**
+  Print the list of zones that have at least one key stored in the configured KASP
+  database.
+
+**-x**, **--mono**
+  Don't generate colorized output.
+
+**-X**, **--color**
+  Force colorized output in the normal mode.
+
+**-h**, **--help**
+  Print the program help.
+
+**-V**, **--version**
+  Print the program version.
+
+.. NOTE::
+   Keymgr runs with the same user privileges as configured for :doc:`knotd<man_knotd>`.
+   For example, if keymgr is run as ``root``, but the configured :ref:`user<server_user>`
+   is ``knot``, it won't be able to read files (PEM files, KASP database, ...) readable
+   only by ``root``.
+
+Commands
+........
+
+**list** [*timestamp_format*]
+  Prints the list of key IDs and parameters of keys belonging to the zone.
+
+**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).
+
+**import-pub** *BIND_pubkey_file*
+  Imports a public key into KASP database. This key won't be rolled over nor used for signing.
+  Takes one argument: path to BIND public key file.
+
+**import-pem** *PEM_file* [*arguments*...]
+  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.
+
+**import-pkcs11** *key_id* [*arguments*...]
+  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.
+
+**nsec3-salt** [*new_salt*]
+  Prints the current NSEC3 salt used for signing. If *new_salt* is specified, the salt is overwritten.
+  The salt is printed and expected in hexadecimal, or dash if empty.
+
+**local-serial** [*new_serial*]
+  Print SOA serial stored in KASP database when using on-secondary DNSSEC signing.
+  If *new_serial* is specified, the serial is overwritten. After updating the serial, expire the zone
+  (**zone-purge +expire +zonefile +journal**) if the server is running, or remove corresponding zone file
+  and journal contents if the server is stopped.
+
+**master-serial** [*new_serial*]
+  Print SOA serial of the remote master stored in KASP database when using on-secondary DNSSEC signing.
+  If *new_serial* is specified, the serial is overwritten (not recommended).
+
+**set** *key_spec* [*arguments*...]
+  Changes a timing argument (or ksk/zsk) of an existing key to a new value. *Key_spec* is either the
+  key tag or a prefix of the key ID, with an optional *[id=|keytag=]* prefix; *arguments* 
+  are like for **generate**, but just the related ones.
+
+**ds** [*key_spec*]
+  Generate DS record (all digest algorithms together) for specified key. *Key_spec*
+  is like for **set**, if unspecified, all KSKs are used.
+
+**dnskey** [*key_spec*]
+  Generate DNSKEY record for specified key. *Key_spec*
+  is like for **ds**, if unspecified, all KSKs are used.
+
+**delete** *key_spec*
+  Remove the specified key from zone. If the key was not shared, it is also deleted from keystore.
+
+**share** *key_ID* *zone_from*
+  Import a key (specified by full key ID) from another zone as shared. After this, the key is
+  owned by both zones equally.
+
+Commands related to Offline KSK feature
+.......................................
+
+**pregenerate** [*timestamp-from*] *timestamp-to*
+  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.
+
+**show-offline** [*timestamp-from*] [*timestamp-to*]
+  Print pre-generated offline key-related records for specified time interval. If *timestamp_to*
+  is omitted, it will be to infinity. If *timestamp-from* is omitted, it will start from the
+  beginning.
+
+**del-offline** *timestamp-from* *timestamp-to*
+  Delete pre-generated offline key-related records in specified time interval.
+
+**del-all-old**
+  Delete old keys that are in state 'removed'. This function also applies to
+  non-offline KSK keys.
+
+**generate-ksr** [*timestamp-from*] *timestamp-to*
+  Print to stdout KeySigningRequest based on pre-generated ZSKs for specified time period.
+  If *timestamp-from* is omitted, timestamp of the last offline records set is used
+  or now if no records available.
+
+**sign-ksr** *ksr_file*
+  Read KeySigningRequest from a text file, sign it using local keyset and print SignedKeyResponse to stdout.
+
+**validate-skr** *skr_file*
+  Read SignedKeyResponse from a text file and validate the RRSIGs in it if not corrupt.
+
+**import-skr** *skr_file*
+  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.
+
+Generate arguments
+..................
+
+Arguments are separated by space, each of them is in format 'name=value'.
+
+**algorithm**
+  Either an algorithm number (e.g. 14) or :ref:`algorithm name<policy_algorithm>`
+  without dashes (e.g. ECDSAP384SHA384).
+
+**size**
+  Key length in bits.
+
+**ksk**
+  If set to **yes**, the key will be used for signing DNSKEY rrset. The generated key will also
+  have the Secure Entry Point flag set to 1.
+
+**zsk**
+  If set to **yes**, the key will be used for signing zone (except DNSKEY rrset). This flag can
+  be set concurrently with the **ksk** flag.
+
+**sep**
+  Overrides the standard setting of the Secure Entry Point flag.
+
+The following arguments are timestamps of key lifetime (see :ref:`DNSSEC Key states`):
+
+**pre_active**
+  Key started to be used for signing, not published (only for algorithm rollover).
+
+**publish**
+  Key published.
+
+**ready**
+  Key is waiting for submission (only for KSK).
+
+**active**
+  Key used for signing.
+
+**retire_active**
+  Key still used for signing, but another key is active (only for KSK or algorithm rollover).
+
+**retire**
+  Key still published, but no longer used for signing.
+
+**post_active**
+  Key no longer published, but still used for signing (only for algorithm rollover).
+
+**revoke**
+  Key revoked according to :rfc:`5011` trust anchor roll-over.
+
+**remove**
+  Key deleted.
+
+Timestamps
+..........
+
+0
+  Zero timestamp means infinite future.
+
+*UNIX_time*
+  Positive number of seconds since 1970 UTC.
+
+*YYYYMMDDHHMMSS*
+  Date and time in this format without any punctuation.
+
+*relative_timestamp*
+  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).
+
+Exit values
+-----------
+
+Exit status of 0 means successful operation. Any other exit status indicates
+an error.
+
+Examples
+--------
+
+1. Generate new TSIG key::
+
+    $ keymgr -t my_name hmac-sha384
+
+2. Generate new DNSSEC key::
+
+    $ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \
+      ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y
+
+3. Import a DNSSEC key from BIND::
+
+    $ keymgr example.com. import-bind ~/bind/Kharbinge4d5.+007+63089.key
+
+4. Configure key timing::
+
+    $ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
+
+5. Share a KSK from another zone::
+
+    $ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another-zone.com.
+
+See Also
+--------
+
+:rfc:`6781` - DNSSEC Operational Practices.
+:rfc:`7583` - DNSSEC Key Rollover Timing Considerations.
+
+:manpage:`knot.conf(5)`,
+:manpage:`knotc(8)`,
+:manpage:`knotd(8)`.