Security

Active contributors: johnbelamaric, miekg, ihac, isolus, chrisohaver

Purpose

These plugins enforce who can ask, what they can ask, and what's signed. They sit either at the start of the chain (filtering) or wrap the response (signing).

Plugins in this group

Plugin	Source	One-liner
acl	plugin/acl/	Allow/deny queries by client CIDR or DNS class/type
view	plugin/view/	Scope a server block to clients matching a CEL-like expression
tsig	plugin/tsig/	Verify TSIG-signed queries against named secrets
dnssec	plugin/dnssec/	On-the-fly DNSSEC signing of any answer (NSEC black lies)
sign	plugin/sign/	Pre-sign zone files on disk (DNSSEC)
tls	plugin/tls/	Configure TLS for DoT/DoH/DoH3/DoQ/gRPC servers

How they fit

graph TD
    Q[query]
    Q --> View{view filter}
    View -->|no match| OtherBlock[other server block]
    View -->|match| TSIG[tsig]
    TSIG -->|invalid sig| Refused[REFUSED]
    TSIG -->|valid| ACL[acl]
    ACL -->|deny| Refused
    ACL -->|allow| Chain[downstream plugins]
    Chain --> DNSSEC[dnssec wrap response]
    DNSSEC --> Reply[reply]

• view is processed in core/dnsserver: it contributes a FilterFunc to the Config, evaluated before the chain runs.
• tsig validates signed messages via the per-server TsigSecret map populated from the Caddyfile.
• acl matches a request's client IP, qclass, qtype, and qname against a list of allow/block/refuse/drop/filter rules, encoded with expression.
• dnssec and sign are siblings: sign runs outside the server (offline signing of master files) while dnssec runs in-process and signs at request time.

Notable plugins in detail

view

Implements Viewer (core/dnsserver/view.go). Each view plugin instance contributes a Filter(ctx, req) function evaluated in Server.ServeDNS before dispatch. The filter is parsed by plugin/pkg/expression and exposes variables like client_ip, proto, qtype, qname. Unmatched server blocks are skipped, allowing two blocks for the same zone to serve different content to different clients. Two views in the same block error out at setup time.

acl

Pure-Go expression evaluator over IPs and DNS metadata. Rules:

acl {
    block type ANY
    allow net 192.168.0.0/16
    block
}

Actions are allow, block (REFUSED), refuse (legacy), drop (no response), filter (NOERROR with empty answer). The evaluator is in plugin/acl/handler.go. Common in zero-trust setups where DNS is itself an attack surface.

tsig

Verifies inbound TSIG. The Caddyfile configures secret <name> <key> entries that are propagated to Config.TsigSecret and consumed by the underlying miekg/dns.Server. Useful for AXFR authentication.

dnssec

The on-the-fly signer. From the README.md:

With dnssec, any reply that doesn't (or can't) do DNSSEC will get signed on the fly. Authenticated denial of existence is implemented with NSEC black lies. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA). NSEC3 is not supported.

Implementation:

• Keys come from disk (key file) or AWS Secrets Manager (key aws_secretsmanager). Each key has its DNSKEY type derived from the SEP bit.
• Signed RRSIGs are cached in a sharded LRU keyed by (name, type, dnssec_alg). Capacity is configurable via cache_capacity.
• The plugin wraps the downstream writer to inspect the message, sign each RRset, and append RRSIG and NSEC records. Implementation lives in plugin/dnssec/handler.go, dnssec.go, and responsewriter.go.

sign

Offline signer. Reads a master file, signs every record, and writes a signed master file to disk for the file plugin to serve. Useful when on-the-fly signing isn't desired (CPU cost, DNSKEY rotation control).

tls

Doesn't directly handle DNS — instead, populates Config.TLSConfig so DoT, DoH, DoH3, DoQ, and gRPC servers can use it. Uses plugin/pkg/tls to assemble the *tls.Config. Multiple tls blocks across the same server block error out (transports require a single config).

Cross-plugin notes

• view runs before the plugin chain; acl runs inside the chain. Use view for hard tenant separation, acl for firewall-style rules.
• dnssec and transfer cooperate: zone transfers expose signed records when both are loaded.
• tls is required for DoT/DoH/DoH3/DoQ/gRPC encrypted servers; the Transports page lists which servers consult Config.TLSConfig.
• tsig honors the TsigSecret map referenced by Server.serverDNS.

Key source files

File	Purpose
plugin/view/view.go, plugin/view/setup.go	View implementation
core/dnsserver/view.go	Viewer interface
plugin/acl/handler.go, plugin/acl/setup.go	ACL evaluator
plugin/tsig/tsig.go	TSIG verification
plugin/dnssec/dnssec.go, handler.go, responsewriter.go, cache.go	On-the-fly signing
plugin/sign/sign.go, signer.go	Offline signing
plugin/tls/tls.go	TLS configuration
plugin/pkg/tls/	Shared TLS builder
plugin/pkg/expression/	Expression evaluator (for acl and view)

Related pages

• Transports — encrypted servers that consume tls.
• Backends — transfer cooperates with DNSSEC for signed AXFR.
• DNS server — Viewer integration in dispatch.