auto make -f Makefile.doc

Signed-off-by: coredns[bot] <bot@bot.coredns.io>

1 files changed, 150 insertions, 0 deletions

diff --git a/man/coredns-tsig.7 b/man/coredns-tsig.7
new file mode 100644
index 000000000..9716515fa
--- /dev/null
+++ b/man/coredns-tsig.7
@@ -0,0 +1,150 @@
+.\" 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.
+