TSIG Keys on Your Primary DNS Server: BIND, PowerDNS, NSD and Knot
What You Need
A TSIG key signs every zone transfer between your primary server and our secondaries. Your primary then authenticates our servers by the key, not by their IP addresses.
You need three things from the SecondDNS dashboard:
1. The key. Create it in Settings › DNS. The dialog shows the key name, the algorithm (hmac-sha256 or hmac-sha512) and the secret. The secret is shown once: copy it before closing the dialog. If you lose it, regenerate the key. 2. Our nameserver addresses for NOTIFY. They are listed on the Add zone page and in the key dialog. The examples below use 192.0.2.10 and 2001:db8::10; replace them with your addresses. 3. The key name, for example `user_ab12cd34-primary`. It is your account name plus the label you chose.
In every example replace `SECRET_FROM_DASHBOARD` with your secret and `example.com` with your zone. Use the algorithm your key was created with.
New to secondary DNS? Start with How to Set Up a Secondary DNS Server, then come back here to sign the transfers.
How TSIG Works
TSIG (Transaction Signature, RFC 8945, which replaced RFC 2845) adds a signature record to a DNS message. Both sides hold the same secret. The sender computes an HMAC over the message, the key name, the algorithm and the time it signed; the receiver computes the same HMAC with its copy of the secret and compares.
For a zone transfer this happens in both directions. Our secondary signs its AXFR or IXFR request; your primary checks the signature, and if the key is allowed for the zone, sends the zone with its own signature, which our side verifies in turn. A transfer that fails either check is dropped.
Three properties matter in practice:
– The secret never travels. Only the signature does. Anyone who captures the traffic sees the zone data, but cannot produce a valid request. – Time is part of the signature. Each signature carries the signing time and an allowed clock difference (usually 300 seconds). A request outside that window is refused with BADTIME, which is why both servers need a correct clock. – TSIG authenticates, it does not encrypt. The zone still crosses the network in clear text. If the content itself is sensitive, TSIG is not the tool for that; it decides who may pull the zone.
How AXFR and IXFR themselves work, and how NOTIFY triggers them, is covered in Understanding AXFR Zone Transfers.
TSIG or an IP Allow-List
Without a key, your primary decides by source address: our nameserver IPs are in `allow-transfer`, `allow-axfr-ips`, `provide-xfr` or an ACL, and every other address is refused. This works and stays a reasonable default, but it ties your configuration to our addresses.
A key removes that tie. Your primary trusts whoever presents the key, so a change in our addressing, an extra transfer source on our side or a move of your zone to another of our locations does not require you to edit the primary. It also separates customers that share one primary: each SecondDNS account has its own keys, so one account's key cannot pull another account's zones.
You can also combine both. Keep our addresses in the ACL and require the key. In NSD and Knot list our addresses instead of `0.0.0.0/0` together with the key. In BIND an address match list succeeds on any element, so addresses and a key side by side in `allow-transfer` mean address or key; to require both, use the nested form:
allow-transfer { !{ !{ 192.0.2.10; 2001:db8::10; }; any; }; key "user_ab12cd34-primary"; };A transfer then needs the right source and the right key.
Choosing the Algorithm
SecondDNS keys use hmac-sha256 or hmac-sha512. Both are supported by every current release of BIND, PowerDNS, NSD and Knot DNS.
Pick hmac-sha256 unless you have a reason not to: it is the common choice in documentation and examples, and its 32-byte secret is short enough to paste without line breaks. hmac-sha512 uses a 64-byte secret; choose it when a policy on your side asks for it. Older algorithms such as hmac-md5 and hmac-sha1 are not offered.
The algorithm is fixed when the key is created. To change it, create a new key with the other algorithm, switch your zones to it, and delete the old one.
The secret length depends on the algorithm: 32 bytes for hmac-sha256 and 64 bytes for hmac-sha512, which is 44 and 88 characters in base64. Copy the whole secret, including any `=` at the end: without them your primary either rejects the key or computes a different signature, and the transfer ends with BADSIG.
BIND
Add the key and allow transfers signed with it. These are the same blocks the dashboard shows:
key "user_ab12cd34-primary" {
algorithm hmac-sha256;
secret "SECRET_FROM_DASHBOARD";
};
zone "example.com" {
type primary;
file "/etc/bind/zones/example.com.zone";
allow-transfer { key "user_ab12cd34-primary"; };
also-notify { 192.0.2.10; 2001:db8::10; };
};With the key in `allow-transfer` you do not need our IP addresses there. Keep `also-notify`: NOTIFY messages are not signed, and we accept them from your primary's address.
Check the configuration and apply it:
named-checkconf && rndc reconfigWhy NOTIFY matters for how fast changes reach us: Real-time zone sync with NOTIFY.
PowerDNS
Import the key, allow it to transfer the zone, and send NOTIFY to our servers:
# PowerDNS 4.x
pdnsutil import-tsig-key user_ab12cd34-primary hmac-sha256 SECRET_FROM_DASHBOARD
pdnsutil activate-tsig-key example.com user_ab12cd34-primary primary
pdnsutil set-meta example.com ALSO-NOTIFY 192.0.2.10 2001:db8::10
# PowerDNS 5.x
pdnsutil tsigkey import user_ab12cd34-primary hmac-sha256 SECRET_FROM_DASHBOARD
pdnsutil tsigkey activate example.com user_ab12cd34-primary primary
pdnsutil metadata set example.com ALSO-NOTIFY 192.0.2.10 2001:db8::10The zone must be of kind `primary` (or `native` with your own NOTIFY setup). `activate-tsig-key … primary` (`tsigkey activate` in 5.x) adds the key to the zone's `TSIG-ALLOW-AXFR` metadata. PowerDNS gives a request signed with a key in `TSIG-ALLOW-AXFR` access to the zone even when the address is not in `allow-axfr-ips`.
NSD
Define the key in `nsd.conf` and allow transfers only with it:
key:
name: "user_ab12cd34-primary"
algorithm: hmac-sha256
secret: "SECRET_FROM_DASHBOARD"
zone:
name: "example.com"
zonefile: "example.com.zone"
provide-xfr: 0.0.0.0/0 user_ab12cd34-primary
provide-xfr: ::0/0 user_ab12cd34-primary
notify: 192.0.2.10 NOKEY
notify: 2001:db8::10 NOKEY`provide-xfr` with `0.0.0.0/0` and `::0/0` means: from any address, but only with this key. To check both the address and the key, list our addresses instead. NOTIFY goes to our addresses unsigned (`NOKEY`).
Check and apply:
nsd-checkconf /etc/nsd/nsd.conf && nsd-control reconfigKnot DNS
Define the key, an ACL that allows outgoing transfers with it, and our servers as the NOTIFY target:
key:
- id: user_ab12cd34-primary
algorithm: hmac-sha256
secret: SECRET_FROM_DASHBOARD
remote:
- id: seconddns
address: [192.0.2.10, 2001:db8::10]
acl:
- id: seconddns_transfer
key: user_ab12cd34-primary
action: transfer
zone:
- domain: example.com
acl: seconddns_transfer
notify: seconddnsAn ACL with only `key` matches requests from any address signed with that key. Add `address` to the ACL to require both.
Check and apply:
knotc conf-check && knotc reloadCheck the Key Before Adding the Zone
Ask your primary for the zone with the key, from any machine that can reach it on TCP port 53:
dig @PRIMARY_IP example.com AXFR -y hmac-sha256:user_ab12cd34-primary:SECRET_FROM_DASHBOARDA full zone listing means the key and the permission are correct. `BADKEY` means your primary does not know a key with that name; `BADSIG` means the secret or algorithm differs. `Transfer failed` with REFUSED and no TSIG error means the key is valid but not allowed for this zone.
Confirm the Transfer Was Signed
Once the zone is added with the key, your primary logs each transfer together with the key that signed it. In BIND a signed transfer looks like this:
client @0x… 192.0.2.10#43001/key user_ab12cd34-primary (example.com): transfer of 'example.com/IN': AXFR started: TSIG user_ab12cd34-primary (serial 2026101101)The key name after `TSIG` is the one our server used. A transfer logged without a key name means it was allowed by address, not by the key: check that the zone in the dashboard really has the key selected, and remove our addresses from the ACL if you want the key to be required.
In PowerDNS, NSD and Knot DNS look for the zone name in the log at the time of the transfer. On our side the dashboard shows the zone's serial and record count after the first successful transfer.
Select the Key in the Dashboard
When you add a domain, choose the key in the TSIG key field. Your default key, if you set one, is preselected; with None the zone is transferred without a signature. For an existing zone, open its edit dialog and change the key there.
Our servers then sign their transfer requests for the zone with the key. A key reaches our servers only while a zone uses it.
Regenerating a key replaces the secret at once. Zones that use the key stop syncing until your primary has the new secret, so update the primary right after you regenerate.
Rotating a Key
Rotate a key when the secret may have been exposed, when someone who had access to the primary leaves, or on a regular schedule if your policy asks for it.
The order that keeps the gap shortest:
1. Open your primary's configuration so the change is ready to apply. 2. In Settings › DNS, choose Regenerate on the key. The dialog states how many zones use it. Copy the new secret from the dialog that follows. 3. Replace the secret on your primary and reload it right away. 4. Check with the `dig -y` command above, using the new secret.
Between steps 2 and 3 our servers already sign with the new secret, so transfers for those zones fail until your primary has it. The zones keep answering from the last copy we have; only updates wait. If you prefer no gap at all, create a second key, add it to the primary next to the first, switch the zones to it in the dashboard, and delete the old key once nothing uses it.
Troubleshooting
BADKEY: your primary does not know a key with that name. Compare the name in your configuration with the name in the dashboard, including the account prefix.
BADSIG: the secret or the algorithm differs. Copy the secret again, or regenerate the key and update the primary.
BADTIME: TSIG signatures carry a timestamp and are rejected when the clocks differ by more than a few minutes. Keep NTP running on your primary.
Changes reach us late: NOTIFY is not reaching our servers. Check `also-notify`, `ALSO-NOTIFY` or `notify` against our addresses, and that UDP and TCP port 53 are open towards them.
Transfer refused although the key is right: the key is not allowed for this zone. Check `allow-transfer`, `TSIG-ALLOW-AXFR`, `provide-xfr` or the ACL on the zone itself, not only globally.
Frequently Asked Questions
Can one key cover many zones? Yes. Select the same key for each zone in the dashboard and allow it on each zone on your primary. Your plan sets how many keys an account can have.
Can I use a key I generated myself? No. SecondDNS generates the key and shows the secret once, so the secret is never sent to us from outside and is stored only in encrypted form.
Does TSIG change anything for IPv6? No. The key does not depend on the address family. Allow the key, and if you also restrict by address, list our IPv6 addresses as well as the IPv4 ones.
Is NOTIFY signed? No. Your primary sends NOTIFY unsigned, and we accept it from your primary's address. A NOTIFY only tells us to check the serial; the transfer that follows is signed.
Are incremental transfers (IXFR) signed too? Yes. The key applies to both AXFR and IXFR requests for the zone.
What happens if I delete the key on my primary but keep it selected in the dashboard? Transfers start failing with BADKEY. The zone keeps answering from our last copy until it expires according to the SOA expire value (what the SOA timers mean), so fix the configuration or switch the zone to None in time.
Can I delete a key that zones still use? No. The dashboard shows which zones use it; switch them to another key or to None first.
Do I need to open any ports besides 53? No. Transfers use TCP port 53 and NOTIFY uses UDP port 53. TSIG adds no ports: the signature travels inside the same DNS message.
Can I see which keys my zones use? Yes. In Settings › DNS each key shows how many zones use it, and each zone card shows its key name next to the primary's address.