Adding upstream version 2.7.6.upstream/2.7.6upstream

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

1 files changed, 216 insertions, 0 deletions

diff --git a/doc/man_keymgr.rst b/doc/man_keymgr.rst
new file mode 100644
index 0000000..03409b6
--- /dev/null
+++ b/doc/man_keymgr.rst
@@ -0,0 +1,216 @@
+.. highlight:: console
+
+keymgr – Key management utility
+===============================
+
+Synopsis
+--------
+
+:program:`keymgr` *basic_option* [*parameters*...]
+
+:program:`keymgr` [*config_option* *config_storage*] *zone* *command* *argument*...
+
+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.
+
+Basic options
+.............
+
+**-h**, **--help**
+  Print the program help.
+
+**-V**, **--version**
+  Print the program version.
+
+**-t**, **--tsig** *tsig_name* [*tsig_algorithm*] [*tsig_bits*]
+  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 `stdout`: the command does not create a file, nor include the
+  key in a keystore.
+
+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.
+
+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 rollovered 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.
+
+**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; *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*
+  Import a key (specified by full key ID) from another zone as shared. After this, the key is
+  owned by both zones equally.
+
+Generate arguments
+..................
+
+Arguments are separated by space, each of them is in format 'name=value'.
+
+**algorithm**
+  Either an algorithm number (e.g. 14), or text name 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 for the generated key.
+
+The following arguments are timestamps of key lifetime:
+
+**created**
+  Key created.
+
+**pre_active**
+  Key started to be used for signing, not published (only for algorithm rollover).
+
+**publish**
+  Key published.
+
+**ready**
+  Key used for signing and submitted to the parent zone (only for KSK).
+
+**active**
+  Key used for signing.
+
+**post_active**
+  Key still used for singing, but another key is active (only for KSK).
+
+**retire_active**
+  Key no longer published, but still used for signing (only for algorithm rollover).
+
+**retire**
+  Key still published, but no longer used for signing.
+
+**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).
+
+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
+
+See Also
+--------
+
+:rfc:`6781` - DNSSEC Operational Practices.
+:rfc:`7583` - DNSSEC Key Rollover Timing Considerations.
+
+:manpage:`knot.conf(5)`,
+:manpage:`knotc(8)`,
+:manpage:`knotd(8)`.