TSIG Setup Guide

Secure zone transfers with TSIG (Transaction Signature) authentication.

What is TSIG?

TSIG uses shared-secret HMAC authentication to verify that zone transfer requests come from authorized servers. Without TSIG, anyone who knows your server IP could request a zone transfer. TSIG adds a cryptographic signature to each DNS message.

1. Generate a TSIG Key

Generate a random TSIG secret using tsig-keygen (part of BIND) or openssl:

terminal
# Using tsig-keygen (BIND)
$ tsig-keygen -a hmac-sha256 hiddenprimary-transfer
 
# Or using openssl
$ openssl rand -base64 32
k7sHd9fG3mN1pQ...

2. Configure Your Hidden Primary

Add the TSIG key to your DNS server configuration.

BIND

named.conf
key "hiddenprimary-transfer" {
  algorithm hmac-sha256;
  secret "k7sHd9fG3mN1pQ...";
};
 
zone "example.ch" {
  type master;
  file "/etc/bind/zones/example.ch";
  allow-transfer { key "hiddenprimary-transfer"; };
};

Knot DNS

knot.conf
key:
  - id: hiddenprimary-transfer
    algorithm: hmac-sha256
    secret: k7sHd9fG3mN1pQ...
 
acl:
  - id: hiddenprimary-acl
    key: hiddenprimary-transfer
    action: transfer

NSD

nsd.conf
key:
  name: "hiddenprimary-transfer"
  algorithm: hmac-sha256
  secret: "k7sHd9fG3mN1pQ..."

3. Add TSIG to Your Zone in hiddenprimary.ch

When creating or editing a zone, provide the TSIG key name, algorithm, and secret:

terminal
$ curl -X POST https://hiddenprimary.ch/v1/zones \
  -H "Authorization: Bearer $HP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.ch",
    "primary_ips": ["192.0.2.1"],
    "tsig_key_name": "hiddenprimary-transfer",
    "tsig_algorithm": "hmac-sha256",
    "tsig_secret": "k7sHd9fG3mN1pQ..."
  }'

Supported Algorithms

AlgorithmRecommended
hmac-sha256recommended
hmac-sha384supported
hmac-sha512supported
hmac-sha1legacy only
hmac-md5legacy only

We recommend hmac-sha256 for all new setups.

Next Steps