manpagez: man pages & more
man keymgr(8)
Home | html | info | man
keymgr(8)                          Knot DNS                          keymgr(8)


NAME

       keymgr - Knot DNS key management utility


SYNOPSIS

       keymgr [config_option] [options] zone_name command

       keymgr [config_option] [options] keystore_id command

       keymgr [config_option] [-j] -l

       keymgr -t parameter...


DESCRIPTION

       The 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
              /usr/local/etc/knot/knot.conf).

       -C, --confdb directory
              Use a binary configuration database directory (default is
              /usr/local/var/lib/knot/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 name (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. The option -VV makes the program
              print the compile time configuration summary.

       NOTE:
          Keymgr runs with the same user privileges as configured for knotd.
          For example, if keymgr is run as root, but the configured 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.

   Keystore commands

       keystore-test
              Conduct some tests on the specified keystore. For each
              algorithm, key generation, import, removal, and use (signing and
              verification) are tested.  Use a configured keystore_id or - for
              the default.

       keystore-bench [num_threads]
              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 keystore_id or - for the default.

   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 algorithm 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 (for a CSK key).

       sep    Overrides the standard setting of the Secure Entry Point flag.

       The following arguments are timestamps of key lifetime (see 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 (only if ZSK), 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. Import a CSK DNSSEC key from a PEM file:

             $ keymgr example.com. import-pem 085d3890e8c22d854586678d9263933f2d02d795.pem ksk=yes zsk=yes

       5. Configure key timing:

             $ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi

       6. 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.

       knot.conf(5), knotc(8), knotd(8).


AUTHOR

       CZ.NIC Labs <https://www.knot-dns.cz>


COPYRIGHT

       Copyright 2010-2024, CZ.NIC, z.s.p.o.

3.4.1                             2024-10-14                         keymgr(8)

knot 3.4.1 - Generated Tue Oct 15 07:12:11 CDT 2024
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.