DNST-KEYSET(1)

📦 version 0.2.0, in nixpkgs unstable

💅 dnst-keyset(1) 💅

okay bestie, welcome to the dnst-keyset page — it's part of the dnst manual, and it's giving very important plumbing. grab a snack, we're doing DNSSEC key management 🎀

✨ NAME ✨

dnst-keyset — manage DNSSEC signing keys for a domain 💖

🌸 SYNOPSIS 🌸

dnst keyset -c <CONF> [OPTIONS] <COMMAND> [ARGS]

🦋 DESCRIPTION 🦋

okay so the keyset subcommand manages a whole set of DNSSEC (that's RFC 9364, periodt) signing keys, and it generates a signed DNSKEY RRset for you. it's literally meant to be part of a DNSSEC signing solution — not the whole thing. a separate zone signer (which is not part of dnst, just so we're clear) is expected to take the zone signing keys out of the key set, sign the zone, and include the DNSKEY RRset (plus the CDS and CDNSKEY RRsets, obviously 🫶). the keyset subcommand supports keys stored in files, and — when the dnst program is built with the kmip feature flag — keys stored in a Hardware Security Module (HSM) that can be accessed using the Key Management Interoperability Protocol (that's KMIP, iykyk 🔥).

the keyset subcommand operates on one zone at a time, bestie. one. at. a. time. 💅 for each zone, keyset maintains a configuration file that stores configuration parameters for key generation (which algorithm to use, whether to use a CSK or a KSK and ZSK pair), parameters for key rolls (whether key rolls are automatic or not), the lifetimes of keys and signatures, etc. the keyset subcommand also maintains a state file for each zone. the state file lists the keys in the key set, the current key roll state, and has the DNSKEY, CDS, and CDNSKEY RRsets.

okay so the page literally repeats that bit again like it forgot it already said it 😭 — no cap, here's the repeat: key generation (which algorithm to use, whether to use a CSK and a KSK and a ZSK), parameters for key rolls (whether key rolls are automatic or not), the lifetimes of keys and signatures, etc. and yep, the keyset subcommand also maintains state file for each zone. iconic of it to say it twice honestly 🎀

in addition to the configuration and state files, keyset maintains files for keys that are stored in the filesystem. additionally, keyset can optionally maintain a credentials file that contains user names and passwords for the KMIP connections 🔐.

the keyset subcommand uses the Keyset type from the Rust Domain crate to store the set of keys together with their properties — things like whether a key should sign the zone, and timestamps for when keys are created or become stale. the Keyset data type also implements the basic logic of key rolls, so it's lowkey doing the thinking for you 🧠✨.

the keyset subcommand supports importing existing keys — both standalone public keys and public/private key pairs can be imported. a standalone public key can only be imported from a file, whereas public/private key pairs can be either files or references to keys stored in an HSM. 💀 important: the public and private key either need to be both files or both stored in an HSM — no mixing and matching, fr fr.

🧚 Signer 🧚

the zone signer is expected to read the state file that keyset maintains, so it can find the current zone signing keys, find the signed DNSKEY/CDS/CDNSKEY RRset, and find the KMIP configuration 👑

see <ref> for a description of the state file 👀

the signer needs to poll the state file for changes. if the signer is in full control of running keyset, then the state file needs to be checked for changes after running keyset with commands that can potentially change the state file (status subcommands, etc. do not change the state file — those are just vibes). but if keyset can be invoked independently of the signer, then the signer needs to periodically check for changes — for example, at least every hour ⏰.

🌈 Cron 🌈

the signatures of the DNSKEY, CDS and CDNSKEY RRsets need to be updated periodically. on top of that, key roll automation requires periodic invocation of keyset to start new key rolls and to make progress on the ones that are currently executing 🌀.

for this purpose, keyset has a cron subcommand. this subcommand handles any house keeping work that needs to be done. the cron subcommand can be executed at regular times — for example, once an hour from the cron(1) utility 🕐.

but wait, there's more bestie: keyset also maintains a field in the state file called cron-next, which specifies when the cron subcommand should be run next. running the cron subcommand early is fine — the current time is compared again the cron-next field, and the subcommand exits early if cron-next is in the future. but running the cron subcommand late may cause signatures to expire 😭 so don't do that.

🎀 Create / Init 🎀

the initialisation of a key set for a zone consists of two steps, and honestly they're a little duo:

  1. first, the create subcommand creates a configuration file with mostly default values, plus a state file without any keys.
  2. the init subcommand finishes the initialisation ✨

this two step procedure allows configuration parameters to be set between the create and the init subcommand — for example, the algorithm to use. it also allows existing public/private key pairs to be imported 💖.

the init subcommand checks if any public/private key pairs have been imported. if so, init checks if both roles (KSK and ZSK) are present. a single CSK combines both rolls. absent a CSK, both a KSK and a ZSK need to be present, otherwise the init command fails 💀. any imported public keys are ignored by init (sorry, they just don't count 🙈).

if no public/private key pairs have been imported, then the init subcommand will start an algorithm roll. the algorithm roll will create new keys based on the current configuration: either as files or in an HSM, and either a CSK or a pair of KSK and ZSK 👑.

🔥 Key Rolls 🔥

the keyset subcommand can perform four different types of key rolls: KSK rolls, ZSK rolls, CSK rolls and algorithm rolls. let me break it down:

  • a KSK roll replaces one KSK with a new KSK.
  • similarly, a ZSK roll replaces one ZSK with a new ZSK.
  • a CSK roll also replaces a CSK with a new CSK, but the roll also treats a pair of KSK and ZSK keys as equivalent to a CSK. so a CSK roll can also roll from KSK plus ZSK to a new CSK, or from a CSK to new a KSK and ZSK pair. and note that a roll from KSK plus ZSK to a new KSK plus ZSK pair is also supported 🫶
  • finally, an algorithm roll is similar to a CSK roll, but designed in a specific way to handle the case where the new key or keys have an algorithm that is different from one used by the current signing keys 🧠

the KSK and ZSK rolls are completely independent and can run in parallel — main character energy, they don't need each other 💅. consistency checks are performed at the start of a key roll. for example, a KSK key roll cannot start when another KSK is in progress, or when a CSK or algorithm roll is in progress. a KSK roll also cannot start when the current signing key is a CSK, or when the configuration specifies that the new signing key has to be a CSK. finally, KSK rolls are also prevented when the algorithm for new keys is different from the one used by the current key. similar limitations apply to the other roll types. note however that an algorithm roll can be started even when it is not needed 👀 (it's allowed to be extra).

a key roll consists of six steps: start-roll, propagation1-complete, cache-expired1, propagation2-complete, cache-expired2, and roll-done. for each key roll these six steps follow in the same order, no skipping ahead. associated with each step is a (possibly empty) list of actions. actions fall in three categories:

  1. actions that require updating the zone or the parent zone.
  2. actions that require checking if changes have propagated to all nameservers, and require reporting of the TTLs of the changed RRset as seen at the nameservers.
  3. actions that require waiting for changes to propagate to all nameservers, but there's no need to report the TTL.

typically, in a list of actions, an action of the first category is paired with one from the second or third category. for example, UpdateDnskeyRrset is paired with either ReportDnskeyPropagated or WaitDnskeyPropagated ✨.

a key roll starts with the start-roll step, which creates new keys. the next step, propagation1-complete, has a TTL argument which is the maximum of the TTLs of the Report actions. cache-expired1 and cache-expired2 have no associated actions — they simply require waiting for the TTL (in seconds) reported by the previous propagation1-complete or propagation2-complete. the propagation2-complete step is similar to the propagation1-complete step. finally, the roll-done step typically has associated Wait actions. these actions are cleanup actions and are harmless, but confusing if they are skipped 🧹.

the keyset subcommand provides fine grained control over automation. automation is configured separately for each of the four roll types, and for each roll type there are four booleans called start, report, expire and done 🎛️.

when set, the start boolean directs the cron subcommand to start a key roll when a relevant key has expired. a KSK or a ZSK key roll can start automatically if respectively a KSK or a ZSK has expired. a CSK roll can start automatically when a CSK has expired, but also when a KSK or ZSK has expired and the new key will be a CSK. finally, an algorithm roll can start automatically when the new algorithm is different from the one used by the existing keys and any key has expired 🔥.

the report flags control the automation of the propagation1-complete and propagation2-complete steps. when enabled, the cron subcommand contacts the nameservers of the zone, or (in the case of ReportDsPropagated) the nameservers of the parent zone, to check if changes have propagated to all nameservers. the check obtains the list of nameservers from the apex of the (parent) zone and collects all IPv4 and IPv6 addresses 🌐. for the ReportDnskeyPropagated and ReportDsPropagated actions, each address is the queried to see if the DNSKEY RRset or DS RRset match the KSKs. the ReportRrsigPropagated action is more complex:

  1. first the entire zone is transferred from the nameservers specified via set publication-nameservers, or if not set, form the primary nameserver listed in the SOA record.
  2. then all relevant signatures are checked if they have the expected key tags.
  3. the maximum TTL in the zone is recorded to be reported.
  4. finally, all addresses of listed nameservers are checked to see if they have a SOA serial that is greater than or equal to the one that was checked 👑

automation of cache-expired1 and cache-expired2 is enabled by the expire boolean. when enabled, the cron subcommand simply checks if enough time has passed to invoke cache-expired1 or cache-expired2 ⏳.

finally the done boolean enables automation of the roll-done step. this automation is very similar to the report automation — the only difference is that the Wait actions are automated, so propagation is tracked but no TTL is reported 🎀.

fine grained control of over automation makes it possible to automate KSK or algorithm without starting them automatically. or let a key roll progress automatically except that the cache-expired steps must be done manually in order to be able to insert extra manual steps 💅.

⚠️ real talk: the report and done automations require that keyset has network access to all nameservers of the zone and all nameservers of the parent. no network, no automation, periodt 😭

Okay so, the config vars autoremove and autoremove-delay are the ones that control the automatic removal of keys you don’t need anymore. autoremove defaults to false, and in that case stale keys have to be removed manually, bestie. But when autoremove is set to true, the cron subcommand checks if any keys have been stale for at least autoremove-delay, and if so, it removes those keys. The autoremove-delay variable defaults to one week.

🔐 HSM Support (KMIP) 🔐

The keyset subcommand supports keys in Hardware Security Modules (HSM) through the KMIP protocol. The most common way to access keys in HSMs is through the PKCS #11 interface. And okay, the PKCS #11 interface involves loading a shared library into the process that needs to access the HSM. This is unattractive for two reasons:

  1. Loading an arbitrary (binary) shared library negates the memory security features of an application written in Rust. A mistake in the shared library could corrupt memory that is used by the application. For this reason it is attractive to load the shared library into a separate process.
  2. Setting up the run-time environment of the shared library is often complex. The library may require specific environment variables or access to specific files or devices. This complexity impacts every application that wants to use the shared library.

For these reasons it was decided to write a separate program, called kmip2kpcs11, that uses the PKCS #11 standard to have access to an HSM and provides a KMIP server interface. This makes it possible to contain both the configuration complexity and the possibility of memory corruption in a single program. Other programs, such as the keyset subcommand, then use the KMIP protocol to indirectly access the HSM via the kmip2kpcs11 program. Support for the KMIP protocol also makes it possible to directly connect to KMIP capable HSMs. slay ✨

The keyset subcommand stores two pieces of KMIP configuration. The first is a list of KMIP servers. Each KMIP server has a server ID that is used in key references to specify in which server the key is stored. A server also has a DNS name or IP address and a port to connect to the server. The second piece of configuration is the ID of the server to be used for creating new keys. It is possible to specify that no server is to be used for new keys, in that case new keys will be created by keyset and stored as files. 🎀

Authentication can be done either with a user name and password or with a client-side certificate. The user name and password are KMIP concepts that are mapped by the cascade-hsm-bridge server to a PKCS #11 slot or token name and the PIN. With this approach the cascade-hsm-bridge server does not have to store secrets that provide access to the HSM. User names and passwords are stored in a separate file to avoid storing secrets in the keyset configuration or state files. iykyk 🔐

Unlike other configuration, the list of KMIP servers is stored in the state file. The reason for doing that is that signers also need the same KMIP server list to be able to sign a zone. By storing the server list in the state file, a signer has to read only the state file to be able to use KMIP keys.

Options that can be configured for a server include not checking the server’s certificate, specifying the server’s certificate or certificate authority, various connection parameters such as connect timeout, read timeout, write timeout and maximum response size. 🛠️

When generating new keys, the label of the key can have a user supplied prefix. This can be used, for example, to show that a key is for development or testing. Finally, some HSMs allow longer labels than others. On HSMs that allow longer labels than the 32 character default, raising the maximum label length can avoid truncation for longer domain names. On HSMs that have a limit that is lower than the default, setting the correct length avoids errors when creating keys. no cap 💅

📥 Importing Keys 📥

There are three basic ways to import existing keys: public-key, a public/private key pair from files or a public/private key pair in an HSM.

A public key can only be imported from a file. When the key is imported the name of the file is converted to a URL and stored in the key set and the key will be included in the DNSKEY RRset. This is useful for certain migrations and to manually implement a multi-signer DNSSEC signing setup. Note that automation does not work for this case. 🙈

A public/private key pair can be imported from files. It is sufficient to give the name of the file that holds the public key if the filename ends in .key and the filename of the private key is the same except that it ends in .private. If this is not the case then the private key filename must be specified separately. 🗂️

In order to use keys stored in a HSM the dnst keyset kmip add-server subcommand must first be used to associate the KMIP server connection settings with a user defined server ID.

The first server defined becomes the default. If a default KMIP server has been defined it will be used to generate all future keys, unless the dnst keyset kmip disable command is issued. If more than one KMIP server is defined, only one can be the default server at any time. Use the dnst keyset kmip set-default command to change which KMIP server will be used to generate future keys. Note that like all dnst keyset subcommands, the KMIP subcommands set behaviour for a single zone. Additionally there are list-servers, get-server, modify-server and remove-server subcommands for inspecting and altering the configured KMIP server settings. 👑

Importing a public/private key stored in an HSM requires specifying the KMIP server ID, the ID of the public key, the ID of the private key, the DNSSEC algorithm of the key and the flags (typically 256 for a ZSK and 257 for a KSK). 🔑

Normally, keyset assumes ownership of any keys it holds. This means that when a key is deleted from the key set, the keyset subcommand will also delete the files that hold the public and private keys or delete the keys from the HSM that was used to create them.

For an imported public/private key pair this is considered too dangerous because another signer may need the keys. For this reason keys are imported in so-called decoupled state. When a decoupled key is deleted, only the reference to the key is deleted from the key set, the underlying keys are left untouched. There is a --coupled option to tell keyset to take ownership of the key. 🫶

🚚 Migration 🚚

The keyset subcommand has no direct support for migration. Migration has to be done manually using the import commands. The semantics of the import commands are described in the previous section. This section focuses on how the import command can be used to perform a migration.

There are three migration strategies: 1) importing the existing signer’s (private) signing keys, 2) a full multi-signer migration and 3) a partial multi-signer migration. 🌈

🧨 Importing the existing signer's signing keys 🧨

Importing the existing signer’s public/private key pairs is the easiest migration mechanism. The basic process is the following:

  • Disable (automatic) key rolls on the existing signer.
  • Disable automatic key rolls before executing the create command. For example by setting the KSK, ZSK, and CSK validities to off.
  • Import the KSK and ZSK (or CSK) as files or using KMIP between the create and init commands.
  • Check with tools such as ldns-verify-zone that the new zone is secure with the existing DS record at the parent.
  • Switch the downstream secondaries that serve the zone to receive the signed zone from the new signer.
  • Perform key rolls for the KSK and ZSK (or the CSK).
  • (If wanted) enable automatic key rolls.
  • Remove the zone from the old signer.

Note that after the key roll, the signer has to make sure that it keeps access to signing keys. In case of KMIP keys, the old signer can also delete the keys from the HSM. For this reason it is best to perform key rolls of all keys before removing the zone from the old signer. 😭

This document describes key management. Care should be taken that other parameters, such as the use of NSEC or NSEC3, are the same (to avoid confusion) and that the SOA serial policy is the same (to avoid problems with zone transfers). 🦋

🌈 Full multi-signer migration 🌈

The basic idea is to execute the following steps:

  • Disable (automatic) key rolls on the existing signer.
  • If the parent supports automatic updating of the DS record using CDS/CDNSKEY (RFC 8078) then disable the generation of CDS/CDNSKEY records on the existing signer or disable CDS/CDNSKEY processing for this zone at the parent.
  • Issue the create command.
  • Disable automatic key rolls.
  • (Disable CDS/CDNSKEY generation. keyset cannot disable CDS/CDNSKEY generation at the moment)
  • Import the public key of the existing signer’s ZSK (or CSK) use the keyset import public-key subcommand.
  • Issue the init command.
  • Make sure in the next step to only add a DS record at the parent, not delete the existing one.
  • Complete the initial algorithm roll.
  • Verify using tools such as ldns-verify-zone that the zone is correctly signed.
  • Import the public key of the new ZSK (or CSK) in the existing signer.
  • Verify that all nameservers that serve the zone have the new ZSK in the DNSKEY RRset of the existing signer.
  • Transition the nameservers from the existing signer to the new signer.
  • Let caches expire for the DNSKEY RRset of the old signer and the zone RRSIGs of the old signer.
  • Remove the DS record for the old signer from the parent.
  • Remove the imported public key.
  • (If wanted) enable automatic key rolls and generation of CDS/CDNSKEY records.

🌸 Partial multi-signer migration 🌸

A partial multi-signer migration is the right approach when the existing signer cannot import the new signer’s ZSK. A requirement is that the new signer can transfer the signed zone from the existing signer and that the new signer supports so-called pass-through mode. In pass-through mode a signer leaves signatures for zone records unchanged but does replace the DNSKEY, CDS and CDNSKEY RRset with the ones from this subcommand. ✨

The basic idea is to execute the following steps:

  • Disable (automatic) key rolls on the existing signer.
  • If the parent supports automatic updating of the DS record using CDS/CDNSKEY (RFC 8078) then disable the generation of CDS/CDNSKEY records in the existing signer or disable CDS/CDNSKEY processing for this zone at the parent.
  • Issue the create command.
  • Disable automatic key rolls.
  • (Disable CDS/CDNSKEY generation. keyset cannot disable CDS/CDNSKEY generation at the moment)
  • Import the public key of the existing signer's ZSK (or CSK).
  • Issue the init command.
  • Switch the new signer to pass-through mode. The signer has to transfer the signed zone from the existing signer.
  • Make sure in the next step to only add a DS record at the parent, not delete the existing one.
  • Complete the initial algorithm roll.
  • Verify using tools such as ldns-verify-zone that the zone is correctly signed.
  • Transition the nameservers from the existing signer to the new signer.
  • Let caches expire for the DNSKEY RRset of the old signer.
  • Remove the DS record for the old signer from the parent.
  • Switch off pass-through mode.
  • Let caches expire for the zone RRSIGs of the old signer.
  • Remove the imported public key.
  • (If wanted) enable automatic key rolls and generation of CDS/CDNSKEY records.

✨ OPTIONS ✨

okay these are few and iconic, we love a low-effort section 💅

  • -c — the configuration file. that's it, that's the whole vibe.
  • -h, --help — prints the help text. with -h you get the short summary, with --help you get the long one. so basically -h is the story and --help is the whole trilogy 🫶

🎀 COMMANDS 🎀

the keyset subcommand is where all the action lives. here's the full menu, bestie, no skips:

  • create

makes empty configuration and state files for a domain. blank slate era ✨

  • -n — the name of the domain whose signing keys will be managed.
  • -s — the name of the state file.
  • init

initializes the keyset. here's the tea: if a KSK and ZSK (or a CSK) have already been imported, then the DNSKEY RRset gets created and signed. if there are no keys at all, then a KSK and a ZSK get created (unless the use-csk option is set to true) and an algorithm roll gets started. 🌀

heads up bestie: the init command will fail if the keyset has already been initialized. one shot only, it's giving exclusive 💀
  • ksk, zsk, csk, and algorithm

these four are the manual key roll girlies — they perform manual key roll steps. and they all share these subcommands:

  • start-roll — starts a key roll of the type specified by the command.
  • propagation1-complete <TTL> — tells keyset that the changed RRsets and signatures have propagated. reports the maximum TTL of the report actions.
  • cache-expired1 — tells keyset that enough time has passed that caches should have expired. note that this command will fail if invoked too early. ⏰ no jumping the gun.
  • propagation2-complete <TTL> — this one is similar to propagation1-complete.
  • cache-expired2 — this one is similar to cache-expired1.
  • roll-done — tells keyset that the changed RRsets and signatures have propagated and that any wait actions have been executed successfully. the finale, the curtain call 👑
  • import

the import command can either import a public key in a file, or a public/private key pair in either files or as KMIP references. options within options, we love a nesting doll 🪆

  • public-key <PATH> — a reference to a public key in <PATH> is added to the keyset. imported public keys get added to the DNSKEY RRset.
  • ksk, zsk, csk — a key pair is imported as a KSK, ZSK, or CSK.

okay so when a key gets imported, there's a whole question of what should happen when the imported key is later deleted. by default, keyset imports keys in decoupled state. when a decoupled key is later removed, only the reference is deleted from the key set — the file that contains the key is not deleted, and the key is not deleted from an HSM. passing the option --coupled when importing a key directs keyset to take ownership of the key. 🔐

so the key pair can be imported two ways:

  • file <PATH>

the <PATH> argument refers to the public key. the filename of the private key is derived from the public key unless the --private-key option is used to specify the filename that holds the private key.

  • --coupled — take ownership of the imported keys.
  • --private-key <PATH> — explicitly pass the name of the file that holds the private key.
  • kmip <SERVER> <PUBLIC_ID> <PRIVATE_ID> <ALGORITHM> <FLAGS>

the <SERVER> argument specifies one of the KMIP servers that has been configured using the kmip add-server command. the <PUBLIC_ID> and <PRIVATE_ID> arguments are the KMIP identifiers of the public key and the private key respectively. the DNSSEC algorithm is specified using the <ALGORITHM> argument, and finally the <FLAGS> argument (usually 256 or 257) is the value of the flags field in the DNSKEY record for the public key. 🗂️

  • --coupled — take ownership of the imported keys.
  • remove-key <KEY>

removes a key or key pair from the key set. the <KEY> argument is the URL of the public key. if the key is coupled then the files that hold the keys are also removed or, in the case of KMIP keys, the keys are removed from the HSM. normally, keys are only removed when they are stale. 🗑️

  • --force — force a key to be removed even if the key is not stale.
  • --continue — continue when removing a key file fails or when a key cannot be removed from an HSM.
  • status

gives you status information about key rolls, key expiration, and signature expiration. the gossip command 📊

  • -v --verbose — make status verbose.
  • actions

shows the actions that have to be executed for any key rolls. your to-do list, basically ✅

  • keys

gives detailed information about all keys in the key set. every single one, individually introduced 💖

  • get

gets the values of these configuration variables: use-csk, autoremove, autoremove-delay, algorithm, ds-algorithm, dnskey-lifetime, cds-lifetime. note that this is a subset of all configuration variables, so it's a curated little sampler 🎀

additionally, the dnskey argument returns the current DNSKEY RRset plus signatures, cds returns the CDS and CDNSKEY RRsets plus signatures, and ds returns DS records that should be added to the parent zone.

  • set

sets configuration variables. note that setting configuration variables after the create command but before the init command can be used to affect the initial key creation. timing is everything, bestie ⏳

  • use-csk <BOOLEAN> — when true, new keys will be created as a CSK, otherwise a KSK and a ZSK will be created.
  • autoremove <BOOLEAN> — when true, keys that are stale will be removed automatically.
  • autoremove-delay <DELAY> — sets the delay between the time keys become stale and automatic removal.
  • algorithm <ALGORITHM> — sets the algorithm to be used when creating new keys. supported values are RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, and ED448. not all values are supported for KMIP keys.
    • -b <BITS> — for RSA keys, the length of the key in bits.
  • ksk-roll-type <KSK-ROLL-TYPE> — the type of KSK roll to use. possible values are double-signature-ksk-roll and double-ds-ksk-roll.
  • zsk-roll-type <ZSK-ROLL-TYPE> — the type of ZSK roll to use. possible values are pre-publish-zsk-roll and double-signature-zsk-roll.
  • auto-ksk, auto-zsk, auto-csk, auto-algorithm — these commands take four boolean arguments: <START> <REPORT> <EXPIRE> <DONE>. when set to true, the corresponding step or steps of the key roll specified by the command are executed automatically.

for example, auto-csk true false true false means that CSK rolls will start automatically, that the propagation1-complete, propagation2-complete, and roll-done need to be executed manually, and that the cache-expired1 and cache-expired2 steps are executed automatically. mix and match, you're the director 🎬

  • ds-algorithm <ALGORITHM> — sets the hash algorithm to be used for generating DS records. possible values are SHA-256 and SHA-384.
  • dnskey-lifetime <DURATION>, cds-lifetime <DURATION> — when a DNSKEY RRset is signed (dnskey-lifetime) or when CDS or CDNSKEY RRsets are signed (cds-lifetime), this is how far in the future the signatures are set to expire. the duration is an integer followed by a suffix: s or secs for seconds, m or mins for minutes, h for hours, d for days, w for weeks.
  • dnskey-remain-time <DURATION>, cds-remain-time <DURATION> — the minimum amount of remaining time that signatures for the DNSKEY RRset (dnskey-remain-time) or the CDS or CDNSKEY RRsets (cds-remain-time) have to be valid. new signatures are generated when the remaining time drops below the specified duration. for the syntax of <DURATION> see dnskey-lifetime.
  • dnskey-inception-offset <DURATION>, cds-inception-offset <DURATION> — when generating signatures for the DNSKEY RRset (dnskey-inception-offset) or the CDS and CDNSKEY RRsets (cds-inception-offset), set the inception timestamp this amount in the past to compensate for clocks that are a bit off or in the wrong time zone. for the syntax of <DURATION> see dnskey-lifetime. clock shenanigans, handled 🕰️
  • ksk-validity <DURATION> | off, zsk-validity <DURATION> | off, csk-validity <DURATION> | off — set how long a KSK, ZSK, or CSK is considered valid. the special value off means that no limit has been set. for the syntax of <DURATION> see dnskey-lifetime.

when a key is no longer considered valid and automatic starting of the appropriate key roll has been enabled, then a key roll will start at the next invocation of the cron command.

the status command shows which keys are no longer valid or when their validity will end. 🔥

  • update-ds-command — set a command to run when the DS records in the parent zone need to be updated. this command can, for example, alert the operator or use an API provided by the parent zone to update the DS records automatically. automation girlie behavior 💅
  • tsig-store-path — set the path to a TSIG key store file to use.

keys defined in the store file must use one of the following algorithms:

  • hmac-sha1
  • hmac-sha256
  • hmac-sha384
  • hmac-sha512

currently there is no way to create this file using dnst keyset. the file is in JSON format and defines zero or more TSIG keys as entries in a map. the example below defines a single TSIG key with name tsig-zonedata-ch-public-21-03 using algorithm hmac-sha512 with a base64 encoded secret.

{
  "version": "v1",
  "map": {
    "tsig-zonedata-ch-public-21-01": {
      "alg": "hmac-sha512",
      "data": "stZw...iJ3Q=="
    }
  }
}
  • publication-nameservers — set the nameservers to transfer from when checking a zone.

if no nameserver values are specified, the default behaviour of querying the primary nameserver defined in the SOA record will be used. 🌈

So the nameservers go in as space-separated arguments, babes — each nameserver is one argument, and it looks like this:

<IP_ADDR>:<PORT>[^<TSIG_KEY_NAME>]
  • fake-time — sets the "wall clock" time to use for testing 💅. The argument is either the Unix time in seconds since Epoch, or the literal string off to turn fake-time back off. Time travel, but make it QA ✨
  • show — shows literally every configuration variable. One giant vibe check of your whole config, no gatekeeping 💖
heads up bestie: fake-time only gets printed when it's actually set. Otherwise it's giving invisible 🙈
  • cron — runs any automatic steps, like refreshing signatures or the automatic bits of key rolls. It's the "bestie, go do your chores" command 🧹
  • kmip — this one manages the list of configured KMIP servers and which one is the default for generating new keys 👑. It's got subcommands:
    • disable — disables using KMIP for generating new keys. Bye 👋
    • add-server <SERVER-ID> <NAME-OR-IP> — adds a KMIP server with name <SERVER-ID> and DNS name or IP address <NAME-OR-IP>. The server's name is what gets used in a key reference to figure out which KMIP server is holding the key, iykyk 🔑
      • --port <PORT> — TCP port to connect to the KMIP server on. Default port is 5696.
      • --pending — adds the server but does not make it the default. It's in the group chat but not the admin 💀
      • --credential-store <CREDENTIALS_STORE_PATH> — optional path to a JSON file to read/write username/password credentials from/to.
      • --username <USERNAME> — optional username to authenticate to the KMIP server as.
      • --password <PASSWORD> — optional password to authenticate to the KMIP server with.
      • --client-cert <CLIENT_CERT_PATH> — optional path to a TLS certificate to authenticate to the KMIP server with.
      • --client-key <CLIENT_KEY_PATH> — optional path to a private key for client certificate authentication.
      • --insecure — accepts the KMIP server's TLS certificate without verifying it. Lowkey risky, highkey convenient 🫣
      • --server-cert <SERVER_CERT_PATH> — optional path to a TLS PEM certificate for the server.
      • --ca-cert <CA_CERT_PATH> — optional path to a TLS PEM certificate for a Certificate Authority.
      • --connect-timeout <CONNECT_TIMEOUT> — TCP connect timeout. Default 3 seconds.
      • --read-timeout <READ_TIMEOUT> — TCP response read timeout. Default 30 seconds.
      • --write-timeout <WRITE_TIMEOUT> — TCP request write timeout. Default 3 seconds.
      • --max-response-bytes <MAX_RESPONSE_BYTES> — maximum KMIP response size to accept (in bytes). Default 8192 bytes. No letting the server dump a whole novel on you 📚
      • --key-label-prefix <KEY_LABEL_PREFIX> — can be used to denote the s/w that created the key, and/or to indicate which installation/environment it belongs to, e.g. dev, test, prod, etc. Label your stuff, bestie 🏷️
      • --key-label-max-bytes <KEY_LABEL_MAX_BYTES> — maximum label length (in bytes) permitted by the HSM. Default 32 bytes.
    • modify-server <SERVER-ID> — modifies the settings of the server with ID <SERVER-ID>. This subcommand takes most of the options documented at kmip add-server. Some options have the same name but are slightly different 👀. There are also a few additional options. The new and modified ones are listed below:
      • --address <IP_HOST_OR_FQDN> — modifies the hostname or IP address of the KMIP server.
      • --no-credentials — disables use of username / password authentication.
note: this will remove any credentials from the credential-store for this server id. Gone gone 🫧
  • --no-client-auth — disables use of TLS client certificate authentication.
  • --insecure <BOOLEAN> — modifies whether or not to accept the KMIP server's TLS certificate without verifying it. Yes, it takes an actual <BOOLEAN> here, not just a flag — read the assignment 💅
  • remove-server <SERVER-ID> — removes an existing non-default KMIP server. To remove the default KMIP server you gotta run kmip disable first. And a server can't be removed if there are keys that reference it — it's literally holding keys, be so fr 😭
  • set-default-server <SERVER-ID> — sets the default KMIP server to use for key generation. Main character energy 👑
  • get-server <SERVER-ID> — gets the details of an existing KMIP server. Spill the tea ☕
  • list-servers — lists all configured KMIP servers. Roll call! 🌈

🎀 AUTHOR 🎀

NLnet Labs — icons, honestly 🫶

2024–2026, NLnet Labs

and that's the whole page bestie, you ate that ✨ this was dnst-keyset(1) from version 0.2.0-alpha2, dated May 15, 2026 — go forth and slay your keys 💅🔥👑

📦 where this page comes from