mirror of
https://github.com/coredns/coredns.git
synced 2025-10-31 02:03:20 -04:00
151 lines
3.7 KiB
Groff
151 lines
3.7 KiB
Groff
.\" 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.
|
|
|