ods-kasp(5)

📦
version 2.1.14 · 2 versions
, in centos-stream 10, centos-stream 9, fedora 43, fedora 44, ubuntu noble, ubuntu questing, ubuntu resolute

💖 ods-kasp — the OpenDNSSEC KASP spec, but make it make sense 💖

okay bestie, gather round, because this is ods-kasp(5) and it's literally the blueprint for how OpenDNSSEC signs your zones. no cap. 🎀

✨ SYNOPSIS ✨

/etc/opendnssec/kasp.xml

🌸 DESCRIPTION 🌸

so the kasp file is where you describe the parameters of the DNSSEC Key and Signing Policy (KASP for short) — the policy that gets used to sign zones. every policy is just a lil bundle of parameters that define the way the zone gets signed. that's it, that's the vibe. 💅

🧚 KASP Parameters

a policy has a set of common parameters that exist to identify the policy. like a name tag at a party. 🫶

💜 Policy Name

the name is what links a policy to a zone that needs signing. every policy needs a unique name — no twinning allowed. the policy named "default" is special: it's the one associated with all zones that don't have a policy explicitly associated with them. she's the default friend of the group, iconic. 👑

💜 Policy Description

a policy can have a description associated with it. cute little bonus info.

🦋 Signatures Parameters

this section lists the parameters for the signatures created using the policy. let's get into it.

🌸 Signature Resign Interval

this is the interval between runs of the signer. for example, a zone that has a Re-sign Interval of PT2H (2 hours) gets handled by the signer every 2 hours. clocking in like it's a shift. ⏰

🌸 Signature Refresh Interval

the Refresh Interval describes when a signature should be refreshed. since signatures are typically valid for way longer than the interval between signer runs, there's genuinely no need to regenerate the signatures every single time the signer runs. which means the Re-sign Interval must be smaller than the Refresh Interval. and to actually make refreshing signatures possible, the Re-sign Interval should be at least half of the Refresh Interval. if a signer runs and detects there's no change to the data being signed, signatures may be refreshed. a signature gets refreshed when the time until the signature expiration is closer than the Refresh Interval. ✨

🌸 Signature Validity

the Signature Validity describes how long the signatures are valid for. this parameter groups two pieces of info:

  • the Default Signature Validity — the validity interval for all RRSIG records except those related to NSEC or NSEC3 records.
  • the Denial Signature Validity — for those NSEC/NSEC3 records, the validity period is given by this value instead.

🌸 Signature Jitter

the Signature Jitter (written as j) is the value added to or subtracted from the expiration time of signatures, so that not all signatures expire at the exact same time. the actual value of the jitter is a random value, uniformly ranging between Minus Signature Jitter and Signature Jitter [-j...j]. this value is added to Signature Validity to determine the signature expiration time. keeping them from all showing up to the party at once. 🎉

🌸 Signature Inception Offset

this is a duration subtracted from the time at which a record is signed, to give the inception time of the RRSIG record. it exists to allow for clock skew between the signing system and the system on which the signature is checked. without it, there's a real possibility the checking system could retrieve a signature whose start time is later than the current time. awkward. 😭 the relationship between all these elements is shown below in Figure 1.

 Inception             Signing                          Expiration
    time                  time                             time
     |                     |                           |       |
     |---------------------|---------------------------|.......|.......|
     |                     |                           |       |
                                                       [  +/- Jitter   ]

     |  Inception offset   |                                   |
     |<------------------->|        Validity Interval          |
     |                     |<--------------------------------->|

  Inception             Signing reuse   reuse   reuse   new   Expiration
     time                  time                           signature  time
     |                     |       |       |       |           |
     |---------------------|-----------------------------------|
     |                     |       |       |       |           |
                            <-----> <-----> <----->
                              Re-sign Interval

                                                  |Refresh Interval|
                                                  |<-------------->|
                                                  |                |

              Figure 1: Signature Timing Parameters

🌈 Authenticated Denial of Existence Parameters

authenticated denial of existence — proving that domain names do not exist in the zone — is discussed in this section. below is the list of parameters for creating NSEC or NSEC3 records using the policy. 🔥

⭐ NSEC or NSEC3

if the NSEC scheme is used to implement authenticated denial of existence, there are literally no record elements we can tune. if NSEC3 [RFC5155] is used, there are some more options. so it's giving "NSEC is the low-maintenance one". 🙈

⭐ NSEC3 Opt-Out

whether to enable or disable "opt-out". this is an optimisation meaning NSEC3 records are only created for authoritative data or for secure delegations — insecure delegations get no NSEC3 records. for zones where a majority of the entries are delegations that aren't signed (typically TLDs during the take-up phase of DNSSEC), this reduces the number of DNSSEC records in the zone. slay, efficiency. 💅

⭐ NSEC3 Re-salt Interval

this is the interval between generating new salt values for the hashing algorithm. fresh salt, periodt. 🧂

⭐ NSEC3 Hash Parameters

the NSEC3 Hash Parameters tells parameters related to NSEC3. (yes, that's what it says, bestie — we keep the facts exactly as they are.)

💫 NSEC3 Hash Algorithm

the NSEC3 Hash Algorithm tells what hashing algorithm should be used to create the NSEC3 records.

💫 NSEC3 Hash Iterations

the NSEC3 Hash Iterations shows how many iterations of the hash function should be performed over the original owner name. going around again and again and again. 🔁

💫 NSEC3 Hash Salt Length

the NSEC3 Hash Salt Length provides the length of the salt value to be generated.

💜 Key Parameters

this section covers parameters related to keys. there are a number of parameters relating to both zone-signing keys (ZSK) and key-signing keys (KSK). the dynamic duo. 👑

🎀 DNSKEY TTL

this is the time-to-live value for the DNSKEY resource records.

🎀 Key Retire Safety

the Key Retire Safety is the retire safety margin for the keys. this interval is a safety margin added to calculated timing values, to ensure that keys are retired without there being any chance of signatures created with those keys being considered invalid. safety first, always. 🛟

🎀 Key Publish Safety

the Key Publish is the publish safety margins for the keys. this interval is the safety margin added to calculated timing values, to ensure that keys are published and without there being a chance of signatures created with the keys being considered invalid.

🎀 Key Sharing

if multiple zones are associated with a policy, a key may be shared between zones. for example, if you have 100 zones then you'll only use one set of keys instead of 100 sets. this will save space in your HSM. sharing is caring, fr fr. 🫶

🎀 Key Purging Interval

Key Purging is the event where keys marked as dead (as defined by draft-ietf-dnsop-dnssec-key-timing [key-timing]) get automatically purged from the key database. the Key Purging Interval is the interval of when Key Purging is done. bye bestie, you're archived. 💀

🌸 KSK Parameters

there are parameters specific for the KSK.

⭐ KSK Algorithm

the KSK Algorithm determines the algorithm used for KSKs.

⭐ KSK Lifetime

the KSK Lifetime determines how long the KSK is used for before it must be rolled. (the original says "before it is must be rolled" — we love a typo, we're keeping the meaning: it's gotta roll.)

⭐ KSK Repository

the KSK Repository determines the location of the KSKs.

⭐ Manual KSK Rollover

it may be desirable to force that a key rollover will only be initiated on the command by the operator. note that if KSK rollover is done automatically, there is currently still a step for the KSK that needs manual intervention — where the corresponding DS record for the key needs to be published to the parent before the rollover is completed. so like, even the automatic one has a lil human moment. 🙈

🦋 ZSK Parameters

the same parameters for the KSK are available for the ZSK. the split between the series of parameters is that with a ZSK/KSK Split Signing Scheme, the values for the parameters may be different.

💫 ZSK Algorithm

the ZSK Algorithm determines the algorithm used for ZSKs.

💫 ZSK Lifetime

the ZSK Lifetime determines how long the ZSK is used for before it must be rolled.

💫 ZSK Repository

the ZSK Repository determines the location of the ZSKs.

💫 Manual ZSK Rollover

the ZSK rollover will be fully automatic if Manual ZSK Rollover is disabled. yes bestie, disabling the manual thing makes it automatic, that's the whole bit. ✨

🌈 Zone Parameters

general information concerning the zones is described here.

🧚 Propagation Delay

the Propagation Delay is the amount of time needed for information changes at the master server for the zone to work their way through to all the secondary nameservers. snail mail energy, but for DNS. 🐌

🌸 SOA Parameters

these parameters are necessary for maintaining the SOA record in the signed zone. these values will override values set for the SOA record in the input zone. so like, they win. periodt.

🎀 SOA TTL

this is the time-to-live of the SOA record.

🎀 SOA MINIUM

this is the value for the MINIMUM RDATA element in the SOA record. (spelled MINIUM in the original — we're not fixing it, that's her name now. 💅)

🎀 SOA Serial

this represents the format of the serial number in the signed zone. it's one of the following:

  • counter: use an increasing counter (but use the serial from the unsigned zone if possible).
  • datecounter: use an increasing counter in YYYYMMDDxx format (xx is the number of increments within each day, starting at 00).
  • unixtime: the serial number is set to the "Unix time" (seconds since 00:00 on 1 January 1970 (UTC)) at which the signer is run.
  • keep: keep the serial from the unsigned zone (do not re-sign unless it has been incremented). this way, no signed zone is created unless the zone operator explicitly initiated a zone update.

🎀 Parent Zone Parameters 🎀

So bestie, picture this: your DNSSEC zone is sitting inside a chain of trust, right? That means digest info about the KSKs your zone uses is chilling in DS records over in the parent zone. And the way that works means if you wanna roll keys properly, you have to configure the timing info about the parent zone. No parent-zone timings, no clean rollover. It's giving "you need the receipts from upstairs." 💅

🌸 Propagation Delay 🌸

The Propagation Delay parameter for the parent zone is the interval between the moment a brand new KSK gets published in the zone and the moment that DS record actually shows up in the parent zone. And here's the tea: in reality this is a variable value, it's not gonna sit still for you. So the value you put in the policy for Propagation Delay should be an estimate. Lowkey the whole point is "guess generously." 🙈

🎀 DS TTL 🎀

This one is the DS time-to-live. Set your DS TTL to the TTL of the DS record in the parent zone. That's it, that's the whole vibe. ✨

💜 SOA Parameters 💜

The SOA Parameters for the parent zone give you the info about the parent's SOA record. Are they optional? Absolutely not — they're necessary to calculate the timings in particular rollover scenarios. You need them, periodt. 👑

🦋 SOA TTL 🦋

Set this to the time-to-live of the parent zone SOA record. Matchy-matchy, on purpose. 🫶

⭐ SOA MINIUM ⭐

Set this to the value of the MINIMUM RDATA element in the parent zone SOA record. (Yes, it's spelled MINIUM up there in the heading and we are keeping it exactly as-is — iconic typo, no notes. 😭)

✨ SEE ALSO ✨

Go read these next, fr fr:

👑 AUTHORS 👑

OpenDNSSEC was written by NLnet Labs as part of the OpenDNSSEC project.

http://www.opendnssec.org/

💖 That's a wrap on ods-kasp(5), bestie! This page comes to you from OpenDNSSEC, dated April 2016, and it lives at section ods-kasp(5) in the manual. Go roll those keys responsibly. Slay. 💅✨
📦 where this page comes from