This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

ACME DNS-01 via RFC2136 (TSIG)

Using Knot DNS (Authoritative) and Stalwart Mail

This guide explains how to configure Knot DNS to accept secure RFC2136 dynamic updates using TSIG, and how to configure Stalwart Mail to perform Let's Encrypt DNS‑01 validation through those updates.

This how‑to uses generic domain names (example.com) so it can be safely shared.

---

1. Generate a TSIG Key in Knot

Knot provides the keymgr tool for generating TSIG keys.

keymgr -t tsig.example.com. hmac-sha384

This will output something like:

key:
- id: tsig.example.com.
  algorithm: hmac-sha384
  secret: BASE64SECRETSTRING

Copy the key ID, algorithm, and secret — you will need them in both Knot and Stalwart.

---

2. Add the TSIG Key and ACL to Knot Config

Edit /etc/knot/knot.conf and add the following sections:

# TSIG key
key:
  - id: tsig.example.com.
    algorithm: hmac-sha384
    secret: BASE64SECRETSTRING

# ACL allowing dynamic DNS updates authenticated with this TSIG key
acl:
  - id: acme-update
    action: update
    key: tsig.example.com.

Notes:

• tsig.example.com. must match your keymgr output exactly (including trailing dot).
• The ACL action: update allows RFC2136 UPDATE requests authenticated with this key.

---

3. Attach the ACL to Your Zone

Every zone that ACME should update must reference the ACL. Example:

zone:
  - domain: example.com
    acl: [acme-update]

If you already have other ACLs for secondaries, place acme-update first:

acl: [acme-update, secondary-transfer]

Knot applies ACL rules in order, and the first matching rule wins.

---

4. Reload Knot

Apply the configuration:

sudo knotc reload

---

5. Configure Stalwart Mail (ACME via RFC2136)

Edit stalwart.toml and configure the ACME provider and DNS‑01 challenge:

[acme]
provider = "letsencrypt"
email = "admin@example.com"

[acme.challenge.dns]
method = "rfc2136"

[acme.challenge.dns.rfc2136]
server    = "192.0.2.53"         # IP of your Knot authoritative server
port      = 53
key_name  = "tsig.example.com."  # TSIG key name
key_secret = "BASE64SECRETSTRING" # TSIG secret
algorithm = "HMAC-SHA384"        # Same algorithm used in keymgr

During certificate issuance, Stalwart will:

1. Connect to your Knot server.
2. Use RFC2136 + TSIG to add _acme-challenge.example.com TXT records.
3. Ask Let's Encrypt to validate them.
4. Remove them after validation.

---

6. Restart Stalwart

Apply the config changes:

sudo systemctl restart stalwart-mail

Check the logs to confirm certificate issuance started:

sudo journalctl -u stalwart-mail -f

Look for lines mentioning acme, certificate, or let's encrypt. A successful run ends with something like TLS certificate renewed.

---

7. Verify the Certificate

Once Stalwart has obtained the certificate, confirm it's being served:

openssl s_client -connect mail.example.com:443 -servername mail.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -issuer -dates

The issuer should show Let's Encrypt and the dates should reflect a freshly issued cert.

---

8. Secondary DNS (Optional)

If your zone notifies secondary DNS servers (AXFR/IXFR), Knot will automatically propagate ACME challenge updates to them as well.

Example:

zone:
  - domain: example.com
    notify: [secondary-dns]
    acl: [acme-update]

No special ACME configuration is required for secondaries.

---

9. Security Notes

• Treat the TSIG secret as sensitive as a password.
• Anyone with the key name + secret can modify records allowed by your ACL.
• Use a dedicated ACL scoped only to ACME updates (as shown in step 2) — do not reuse keys for zone transfers or other purposes.

---

Summary

You now have:

• TSIG key generated via Knot's keymgr.
• ACL in Knot allowing authenticated DNS updates.
• Zone configured to use that ACL.
• Stalwart configured to perform DNS‑01 validation via RFC2136.

This setup enables fully automated, secure wildcard and multi-domain certificate issuance via Let's Encrypt.