Provided by: knot_2.1.1-1build1_i386 bug

NAME

       keymgr -  DNSSEC key management utility

SYNOPSIS

       keymgr [global-options] [command...] [arguments...]

       keymgr [global-options] [command...] help

DESCRIPTION

       The keymgr utility serves for key management in Knot DNS server.

       Primarily functions for DNSSEC keys and KASP (Key And Signature Policy)
       management are provided. However the utility  also  provides  functions
       for TSIG key generation.

       The  DNSSEC  and  KASP  configuration  is  stored  in  a so called KASP
       database.  The database  is  simply  a  directory  in  the  file-system
       containing files in the JSON format.

       The  operations  are organized into commands and subcommands. A command
       specifies the operation to be performed with the KASP database.  It  is
       usually  followed  by  named arguments. The special command help can be
       used to list  available  subcommands  in  that  area.  The  listing  of
       available command arguments is not supported yet.

       Command  and argument names are parsed in a smart way. Only a beginning
       of a name can be entered and it will be recognized. The specified  part
       of a name must be unique amongst the other names.

   Global options
       --dir path
              The  location  of  the  KASP  database to work with. Defaults to
              current working directory.

   Main commands
       init   Initialize new  KASP  database  or  upgrade  existing  one.  The
              command  is  idempotent  and  therefore  it  is  safe  to be run
              multiple times.

              The command creates a default policy and default key store (both
              named default). In case of upgrade, existing objects are checked
              and any missing attributes are filled in.

       zone ...
              Operations with zones in the database.  A  zone  holds  assigned
              signing configuration and signing metadata.

       policy ...
              Operations  with  KASP  policies. A policy holds parameters that
              define the way how a zone is signed.

       keystore ...
              Operations with key stores configured for the KASP  database.  A
              private  key  store  holds private key material for zone signing
              separately from the zone metadata.

       tsig ...
              Operations with TSIG keys.

   zone commands
       zone add zone-name [policy policy-name]
              Add a zone into the database. The policy defaults to 'default'.

       zone list [pattern]
              List zones in the database matching the pattern as a substring.

       zone remove zone-name [force]
              Remove a zone from the database.  If  some  keys  are  currently
              active, the force argument must be specified.

       zone set zone-name [policy policy-name]
              Change  zone  configuration. At the moment, only a policy can be
              changed.

       zone show zone-name
              Show zone details.

       zone key list zone-name
              List key IDs and tags of zone keys.

       zone key show zone-name key
              Show zone key details. The key can be a key  tag  or  a  key  ID
              prefix.

       zone key ds zone-name key
              Show  DS  records  for a zone key. The key can be a key tag or a
              key ID prefix.

       zone key generate zone-name [key-parameter...]
              Generate a new key for a zone.

       zone key import zone-name key-file
              Import an existing key in the legacy format. The key-file suffix
              .private  or  .key  is  not  required.  A  public  key without a
              matching private key cannot be imported.

       zone key set zone-name key [key-parameter...]
              Change a key  parameter.  Only  key  timing  parameters  can  be
              changed.

       Available key-parameters:

          algorithm id
                 Algorithm number or IANA mnemonic.

          size bits
                 Size of the key in bits.

          ksk    Set the DNSKEY SEP (Secure Entry Point) flag.

          publish time
                 The time the key is published as a DNSKEY record.

          active time
                 The time the key is started to be used for signing.

          retire time
                 The time the key is stopped to be used for signing.

          remove time
                 The time the key's DNSKEY is removed from the zone.

       The  time accepts YYYYMMDDHHMMSS format, unix timestamp, or offset from
       the current time. For the offset, add + or - prefix  and  optionally  a
       suffix  mi, h, d, w, mo, or y. If no suffix is specified, the offset is
       in seconds.

   policy commands
       policy list
              List policies in the database.

       policy show policy-name
              Show policy details.

       policy add policy-name [policy-parameter...]
              Add a new policy into the database.

       policy set policy-name [policy-parameter...]
              Change policy configuration.

       policy remove policy-name
              Remove a policy from the database.  Note, the utility  does  not
              check if the policy is used.

       Available policy-parameters:

          algorithm id
                 DNSKEY algorithm number or IANA mnemonic.

          dnskey-ttl seconds
                 TTL value for DNSKEY records.  Note, the value is temporarily
                 overridden by the SOA TTL.

          ksk-size bits
                 Size of the KSK.

          zsk-size bits
                 Size of the ZSK.

          zsk-lifetime seconds
                 Period  between  ZSK  publication  and  the   next   rollover
                 initiation.

          rrsig-lifetime seconds
                 Validity period of issued signatures.

          rrsig-refresh seconds
                 Period before signature expiration when the signature will be
                 refreshed.

          nsec3 enable
                 Specifies if NSEC3 will  be  used  instead  of  NSEC.   Note,
                 currently  unused  (the  setting  is  derived from NSEC3PARAM
                 presence in the zone).

          soa-min-ttl seconds
                 SOA Minimum TTL field.  Note, Knot DNS overwrites  the  value
                 with the real used value.

          zone-max-ttl seconds
                 Max TTL in the zone.  Note, Knot DNS will determine the value
                 automatically in the future.

          delay seconds
                 Zone signing and data propagation delay. The value  is  added
                 for safety to timing of all rollover steps.

          manual enable
                 Enable  manual  key  management.  If enabled, no keys will be
                 generated or rolled automatically.

          keystore name
                 Name of the key store to be used for private key material.

   keystore commands
       keystore list
              List names of configured key stores.

       keystore show name
              Show configuration of a key store named name and list key IDs of
              private key material present in that key store.

       keystore add name [backend backend] [config config]
              Configure  new  key  store.  The  name  is  a  unique  key store
              identifier.  The  backend  and  backend-specific   configuration
              string  config  determine where the private key material will be
              physically stored.

       Supported key store backends:

          pkcs8 (default)
                 The backend stores private key material in unencrypted  X.509
                 PEM   files   in   a   directory  specified  as  the  backend
                 configuration string. The path can be specified relatively to
                 the KASP database location.

          pkcs11 The  backend  stores  private key material in a cryptographic
                 token  accessible   via   the   PKCS   #11   interface.   The
                 configuration  string  consists  of  a token PKCS #11 URL and
                 PKCS #11 module path separated by the space character.

                 The format of the PKCS #11 URL is described in RFC  7512.  If
                 the  token  is  protected  by  a  PIN,  make  sure to include
                 pin-value or pin-source attribute in the URL.

                 The PKCS #11 module path can be an absolute path  or  just  a
                 module  name.  In  the later case, the module is looked up in
                 the default modules location.

   tsig commands
       tsig generate name [algorithm id] [size bits]
              Generate new TSIG key and print it on the standard  output.  The
              algorithm  defaults  to  hmac-sha256.  The  default  key size is
              determined optimally based on the selected algorithm.

              The generated key is printed out  in  the  server  configuration
              format  to allow direct inclusion into the server configuration.
              The first line of the output contains a comment with the key  in
              the one-line key format accepted by client utilities.

EXAMPLES

       1. Initialize  a  new KASP database and add a zone example.com with the
          default policy assigned:

             $ keymgr init
             $ keymgr policy add default
             $ keymgr zone add example.com policy default

       2. List zones containing .com substring:

             $ keymgr zone list .com

       3. Add a testing policy lab with rapid key rollovers. Apply the  policy
          to an existing zone:

             $ keymgr policy add lab rrsig-lifetime 300 rrsig-refresh 150 \
                 zsk-lifetime 600 delay 10
             $ keymgr zone set example.com policy lab

       4. Add an existing and already secured zone. Let the keys be managed by
          the KASP. Make sure to import all used keys. Also the used algorithm
          must match with the one configured in the policy:

             $ keymgr zone add example.com policy default
             $ keymgr zone key import example.com Kexample.com+010+12345.private
             $ keymgr zone key import example.com Kexample.com+010+67890.private

       5. Disable  automatic  key  management  for  a  secured  zone. For this
          purpose, create a  policy  named  'manual'  with  otherwise  default
          signing parameters:

             $ keymgr policy add manual manual true
             $ keymgr zone set example.com policy manual

       6. Add  a  zone  to be signed with manual key maintenance. Generate one
          ECDSA signing key. The Single-Type Signing scheme will be used:

             $ keymgr policy add manual manual true
             $ keymgr zone add example.com policy manual
             $ keymgr zone key gen example.com algo 13 size 256

       7. Add a zone to be signed with manual key  maintenance.  Generate  two
          RSA-SHA-256  signing  keys. The first key will be used as a KSK, the
          second one as a ZSK:

             $ keymgr policy add manual manual true
             $ keymgr zone add example.com policy manual
             $ keymgr zone key generate example.com algorithm rsasha256 size 2048 ksk
             $ keymgr zone key generate example.com algorithm rsasha256 size 1024

       8. Generate a TSIG key named operator.key:

             $ keymgr tsig generate operator.key algorithm hmac-sha512

       9. Add a new key store named hsm and backed by  the  SoftHSM  PKCS  #11
          module,  then  add a new policy named secure with default parameters
          using this key store, and finally add  the  zone  example.com  which
          will use this policy:

             $ keymgr keystore add hsm backend pkcs11 \
                 config "pkcs11:token=knot;pin-value=1234 libsofthsm2.so"
             $ keymgr policy add secure keystore hsm
             $ keymgr zone add example.com policy secure

SEE ALSO

       RFC 6781 - DNSSEC Operational Practices.

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

AUTHOR

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

COPYRIGHT

       Copyright 2010–2016, CZ.NIC, z.s.p.o.