mirror of
https://github.com/coredns/coredns.git
synced 2025-10-30 17:53:21 -04:00
119 lines
3.7 KiB
Markdown
119 lines
3.7 KiB
Markdown
# tsig
|
|
|
|
## Name
|
|
|
|
*tsig* - define TSIG keys, validate incoming TSIG signed requests and sign responses.
|
|
|
|
## Description
|
|
|
|
With *tsig*, you can define CoreDNS's TSIG secret keys. Using those keys, *tsig* 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 *tsig*.
|
|
|
|
The *tsig* plugin can also require that incoming requests be signed for certain query types, refusing requests that do not comply.
|
|
|
|
## Syntax
|
|
|
|
~~~
|
|
tsig [ZONE...] {
|
|
secret NAME KEY
|
|
secrets FILE
|
|
require [QTYPE...]
|
|
}
|
|
~~~
|
|
|
|
* **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. Secrets are global to the server instance, not just for the enclosing **ZONE**.
|
|
|
|
* `secrets` **FILE** - same as `secret`, but load the secrets from a file. The file may define any number
|
|
of unique keys, each in the following `named.conf` format:
|
|
```cgo
|
|
key "example." {
|
|
secret "X28hl0BOfAL5G0jsmJWSacrwn7YRm2f6U5brnzwWEus=";
|
|
};
|
|
```
|
|
Each key may also specify an `algorithm` e.g. `algorithm hmac-sha256;`, but this is currently ignored by the plugin.
|
|
|
|
* `require` **QTYPE...** - the query types that must be TSIG'd. Requests of the specified types
|
|
will be `REFUSED` if they are not signed.`require all` will require requests of all types to be
|
|
signed. `require none` will not require requests any types 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
|
|
}
|
|
```
|
|
|
|
## Bugs
|
|
|
|
### Secondary
|
|
|
|
TSIG transfers are not yet implemented for the *secondary* plugin. The *secondary* plugin will not sign its zone transfer requests.
|
|
|
|
### 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://datatracker.ietf.org/doc/html/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 ths 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.
|
|
|
|
|
|
* 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 ths zone of the request matches the _tsig_ plugin zones, _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.
|