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

.SH "NAME"
.PP
\fItsig\fP - validate TSIG requests and sign responses.

.SH "DESCRIPTION"
.PP
With \fItsig\fP, you can define a set of TSIG secret keys for validating incoming TSIG requests and signing
responses. It can also require TSIG for certain query types, refusing requests that do not comply.

.SH "SYNTAX"
.PP
.RS

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

.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.

.RS
.IP \(en 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.

.RE


.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

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

.SS "SPECIAL CONSIDERATIONS FOR FORWARDING SERVERS (RFC 8945 5.5)"
.PP
https://datatracker.ietf.org/doc/html/rfc8945#section-5.5
\[la]https://datatracker.ietf.org/doc/html/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.