coredns/man/coredns-tsig.7

.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-TSIG" 7 "October 2026" "CoreDNS" "CoreDNS Plugins"

.SH "NAME"
.PP
\fItsig\fP - define TSIG keys, validate incoming TSIG signed requests and sign responses.

.SH "DESCRIPTION"
.PP
With \fItsig\fP, you can define CoreDNS's TSIG secret keys. Using those keys, \fItsig\fP validates incoming TSIG requests and signs
responses to those requests. It does not itself sign requests outgoing from CoreDNS; it is up to the
respective plugins sending those requests to sign them using the keys defined by \fItsig\fP.

.PP
The \fItsig\fP plugin can also require that incoming requests be signed for certain query types, refusing requests that do not comply.

.PP
After successfully validating a TSIG record, the plugin adds the normalized key name to the request context. Downstream Go
plugins can call \fB\fCtsig.ValidatedKeyName(ctx)\fR to retrieve the key name and distinguish validated requests from unsigned
requests. The value is not set for requests outside the configured zones because the \fItsig\fP plugin does not validate them.

.SH "SYNTAX"
.PP
.RS

.nf
tsig [ZONE...] {
  secret NAME KEY
  secrets FILE
  require [QTYPE...]
  require\_opcode [OPCODE...]
}

.fi
.RE

.IP \(bu 4
\fBZONE\fP - the zones \fItsig\fP will TSIG.  By default, the zones from the server block are used.
.IP \(bu 4
\fB\fCsecret\fR \fBNAME\fP \fBKEY\fP - specifies a TSIG secret for \fBNAME\fP with \fBKEY\fP. Use this option more than once
to define multiple secrets. Secrets are global to the server instance, not just for the enclosing \fBZONE\fP.
.IP \(bu 4
\fB\fCsecrets\fR \fBFILE\fP - same as \fB\fCsecret\fR, but load the secrets from a file. The file may define any number
 of unique keys, each in the following \fB\fCnamed.conf\fR format:

.PP
.RS

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

.fi
.RE


Each key may also specify an \fB\fCalgorithm\fR e.g. \fB\fCalgorithm hmac-sha256;\fR, but this is currently ignored by the plugin.
.IP \(bu 4
\fB\fCrequire\fR \fBQTYPE...\fP - the query types that must be TSIG'd. Requests of the specified types
will be \fB\fCREFUSED\fR if they are not signed. \fB\fCrequire all\fR will require requests of all types to be
signed. \fB\fCrequire none\fR will not require requests any types to be signed. Default behavior is to not require.
.IP \(bu 4
\fB\fCrequire_opcode\fR \fBOPCODE...\fP - the opcodes that must be TSIG'd. Requests with the specified opcodes
will be \fB\fCREFUSED\fR if they are not signed. Valid opcodes are: \fB\fCQUERY\fR, \fB\fCIQUERY\fR, \fB\fCSTATUS\fR, \fB\fCNOTIFY\fR, \fB\fCUPDATE\fR.
\fB\fCrequire_opcode all\fR will require requests with all opcodes to be signed. \fB\fCrequire_opcode none\fR will not
require requests with any opcode to be signed. Default behavior is to not require.


.SH "EXAMPLES"
.PP
Require TSIG signed transactions for transfer requests to \fB\fCexample.zone\fR.

.PP
.RS

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

.fi
.RE

.PP
Require TSIG signed transactions for all requests to \fB\fCauth.zone\fR.

.PP
.RS

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

.fi
.RE

.PP
Require TSIG signed transactions for UPDATE and NOTIFY operations to \fB\fCdynamic.zone\fR.

.PP
.RS

.nf
dynamic.zone {
  tsig {
    secret dynamic.zone.key. NoTCJU+DMqFWywaPyxSijrDEA/eC3nK0xi3AMEZuPVk=
    require\_opcode UPDATE NOTIFY
  }
}

.fi
.RE

.SH "BUGS"
.SS "SECONDARY"
.PP
TSIG transfers are not yet implemented for the \fIsecondary\fP plugin.  The \fIsecondary\fP plugin will not sign its zone transfer requests.

.SS "ZONE TRANSFER NOTIFIES"
.PP
With the \fItransfer\fP plugin, zone transfer notifications from CoreDNS are not TSIG signed.

.SS "SPECIAL CONSIDERATIONS FOR FORWARDING SERVERS (RFC 8945 5.5)"
.PP
https://www.rfc-editor.org/info/rfc8945/#section-5.5
\[la]https://www.rfc-editor.org/info/rfc8945/#section-5.5\[ra]

.PP
CoreDNS does not implement this section as follows ...

.IP \(bu 4
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.


.PP
CoreDNS behavior:
If ths zone of the request matches the \fItsig\fP plugin zones, then the TSIG record
is always stripped. But even when the \fItsig\fP plugin is not involved, the \fIforward\fP plugin
may alter the message with compression, which would cause validation failure
at the destination.

.IP \(bu 4
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.


.PP
CoreDNS behavior:
If ths zone of the request matches the \fItsig\fP plugin zones, \fIforward\fP plugin will
proxy the request upstream without TSIG.

.IP \(bu 4
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.


.PP
CoreDNS behavior:
The AD flag is not cleared.