COREDNS-TSIG(7)

COREDNS-TSIG(7) — the tsig plugin, explained by your fav Unix gremlin 💅

okay so this is a page from the CoreDNS Plugins manual, and honestly? it's a bop. let's get into it 🫶

---

✨ NAME ✨

tsig — literally what it says on the tin: define TSIG keys, validate incoming TSIG signed requests, and sign the responses. iconic behavior, no notes 👑

---

🌸 DESCRIPTION 🌸

so bestie, with tsig you get to define CoreDNS's TSIG secret keys. and once those keys exist, tsig uses them to do two things:

• validate incoming TSIG requests ✅
• sign the responses to those requests ✅

but here's the important part — tsig does not itself sign requests going out from CoreDNS. nope. that's somebody else's job, fr fr. it's up to the respective plugins sending those requests to sign them using the keys that tsig defined. so tsig is the key holder, not the one signing the outgoing mail 💌

the tsig plugin can also require that incoming requests be signed for certain query types — and it will straight up refuse requests that don't comply. like, no key? no entry. 🚫

and then the techy-but-cool bit: after successfully validating a TSIG record, the plugin adds the normalized key name to the request context. downstream Go plugins can call tsig.ValidatedKeyName(ctx) to grab that key name and tell validated requests apart from unsigned ones. the value is not set for requests outside the configured zones, because the tsig plugin doesn't validate those. makes sense, it's not its zone, not its problem 💁‍♀️

---

🎀 SYNTAX 🎀

tsig [ZONE...] {
  secret NAME KEY
  secrets FILE
  require [QTYPE...]
  require_opcode [OPCODE...]
}

• ZONE — the zones tsig will TSIG. by default, the zones from the server block are used.
• secret NAME KEY — specifies a TSIG secret for NAME with KEY. use this option more than once to define multiple secrets. and heads up: secrets are global to the server instance, not just for the enclosing ZONE.
• secrets FILE — same as secret, but it loads the secrets from a file. the file may define any number of unique keys, each in the following named.conf format:

key "example." {
    secret "X28hl0BOfAL5G0jsmJWSacrwn7YRm2f6U5brnzwWEus=";
};

each key may also specify an algorithm, e.g. algorithm hmac-sha256;, but this is currently ignored by the plugin. so don't come for it, it's just not implemented yet 🙈

• require QTYPE... — the query types that must be TSIG'd. requests of the specified types will be REFUSED if they're not signed. require all will require requests of all types to be signed. require none will not require any types to be signed. default behavior is to not require. (so yeah, opt-in only 💅)
• require_opcode OPCODE... — the opcodes that must be TSIG'd. requests with the specified opcodes will be REFUSED if they're not signed. valid opcodes are: QUERY, IQUERY, STATUS, NOTIFY, UPDATE. require_opcode all will require requests with all opcodes to be signed. require_opcode none will not require requests with any opcode to be signed. default behavior is to not require.

---

🔥 EXAMPLES 🔥

require TSIG signed transactions for transfer requests to example.zone

example.zone {
  tsig {
    secret example.zone.key. NoTCJU+DMqFWywaPyxSijrDEA/eC3nK0xi3AMEZuPVk=
    require AXFR IXFR
  }
  transfer {
    to *
  }
}

require TSIG signed transactions for all requests to auth.zone

auth.zone {
  tsig {
    secret auth.zone.key. NoTCJU+DMqFWywaPyxSijrDEA/eC3nK0xi3AMEZuPVk=
    require all
  }
  forward . 10.1.0.2
}

require TSIG signed transactions for UPDATE and NOTIFY operations to dynamic.zone

dynamic.zone {
  tsig {
    secret dynamic.zone.key. NoTCJU+DMqFWywaPyxSijrDEA/eC3nK0xi3AMEZuPVk=
    require_opcode UPDATE NOTIFY
  }
}

---

💀 BUGS 💀

SECONDARY

TSIG transfers are not yet implemented for the secondary plugin. the secondary plugin will not sign its zone transfer requests. it's giving "we'll get to it" 😭

ZONE TRANSFER NOTIFIES

with the transfer plugin, zone transfer notifications from CoreDNS are not TSIG signed.

SPECIAL CONSIDERATIONS FOR FORWARDING SERVERS (RFC 8945 5.5)

https://www.rfc-editor.org/info/rfc8945/#section-5.5

CoreDNS does not implement this section as follows … 👀

• RFC requirement: If the name on the TSIG is not of a secret that the server shares with the originator, the server MUST forward the message unchanged including the TSIG.

CoreDNS behavior: if the zone of the request matches the tsig plugin zones, then the TSIG record is always stripped. but even when the tsig plugin is not involved, the forward plugin may alter the message with compression, which would cause validation failure at the destination. yeah. 😬

• RFC requirement: If the TSIG passes all checks, the forwarding server MUST, if possible, include a TSIG of its own to the destination or the next forwarder.

CoreDNS behavior: if the zone of the request matches the tsig plugin zones, the forward plugin will proxy the request upstream without TSIG.

• RFC requirement: If no transaction security is available to the destination and the message is a query, and if the corresponding response has the AD flag (see RFC4035) set, the forwarder MUST clear the AD flag before adding the TSIG to the response and returning the result to the system from which it received the query.

CoreDNS behavior: the AD flag is not cleared.

ngl, that whole section is a lot of "here's what the RFC wants vs. here's what we do" — read it carefully if you're forwarding, bestie 🫶

---

okay and that's the whole page!! source is the CoreDNS manual, dated October 2026 — so like, future-dated slay ✨ thanks for reading, mwah 💖🎀🦋