Skip to content
SHC Docs

DNS-domain licensing: the signed token IS the licence, 2026-08-21

Status: OWNER-RULED, ADVERSARIALLY REVIEWED, AMENDED, MERGED. The first cut was reviewed and found to have a hole big enough to void the feature’s whole purpose (§3.1). The cert proof that closes it is the amendment; the review’s other findings are folded in below and marked.

The ruling, in one line: licensing is domain-bound. The vendor mints one signed token per customer domain; the customer publishes it as a TXT record in their own zone; the estate reads its own record and is licensed. There is no licence key to type and no post-deployment registration step.


Nothing about the licence FORMAT changed, and that is the whole design. SHC has exactly one licence token: shclic.v1.<payload>.<signature>, Ed25519 over the payload bytes, domain-bound by the payload’s own domains field (modules/license/format.go, unchanged since the CE/EE split). What this change adds is a second carrier for those identical bytes:

carrierhow the estate gets itwhen you use it
DNS record (primary)the estate resolves _shc-license.<its own domain>the ordinary path; the zone is already in your terraform
installed token (fallback)shc license install <token>a domain whose zone you do not control, a lab name, a bring-up before DNS exists, the unbound vendor fleet blanket

Both take the same value. shc license mint --dns prints it as a record; shc license install takes it as an argument. An operator can copy a value straight out of dig into the install verb and it works.

The terraform that stands an estate up already owns the zone. So the same apply that creates the cluster can create the record that licenses it:

module "cluster" {
source = ".../terraform/modules/shc/hetzner"
license_dns_token = var.license_dns_token # from the vendor, once
bootstrap = { host = "cloud.acme.com", … }
}
resource "hetznerdns_record" "licence" { # your provider, your zone
count = module.cluster.license_dns_record.enabled ? 1 : 0
zone_id = data.hetznerdns_zone.main.id
name = module.cluster.license_dns_record.zone_relative_name
type = "TXT"
ttl = module.cluster.license_dns_record.record_ttl
value = module.cluster.license_dns_record.record_value_quoted
}

The vendor mints once per customer domain. The customer sets one variable. Nobody runs a verb on the estate, ever.

3. Why the signature, and not DNSSEC, and why that was not enough

Section titled “3. Why the signature, and not DNSSEC, and why that was not enough”

The record is public and world-readable. Anybody can read castclaws.com’s licence record and paste it into bitspur.com’s zone.

That copy fails, offline, on a laptop, with the network unplugged. The vendor signature covers the licensed domain, so a token published at the wrong name is a valid signature over the wrong name, and Verifier.VerifyForDomain refuses it against the domain the estate actually serves. Nothing in this scheme trusts DNS to tell the truth; DNS is only asked where the bytes are, never whether they are genuine.

Consequences worth stating plainly, because they are what make the scheme cheap:

  • No DNSSEC dependency. A spoofed answer can only deliver a token that either fails the signature check or is bound to some other domain.
  • No resolver pinning. The estate uses whatever resolver it already has.
  • Works airgapped. The estate resolves its OWN domain, so an airgapped site’s own authoritative server answers and the query never leaves the site. This is also why license.offline (R21, “make zero outbound licensing attempts”) deliberately does not suppress the lookup: that policy is about not phoning the vendor, and this query does not. The kill switch for the lookup itself is license.dns_enabled.

3.1 THE HOLE THE REVIEW FOUND, and the cert proof that closes it

Section titled “3.1 THE HOLE THE REVIEW FOUND, and the cert proof that closes it”

Everything above defends exactly one attack (copy castclaws.com’s record into bitspur.com’s zone), and that is not the attack anyone would run. The real one never touches a zone:

Terminal window
dig +short TXT _shc-license.castclaws.com # the record is public
SHC_HOST=castclaws.com # you assert your own domain

The token is genuine, unexpired, and bound to castclaws.com; the estate says it serves castclaws.com; the signature verifies. Keyed, with the victim’s entitlements. No forgery, no vendor call, nothing detectable offline. The first cut shipped this, and the review demonstrated it empirically.

The root cause is structural: publishing the token made public a value that had never been public, while the only thing standing between that value and a licence was a string the operator asserts about themselves. Domain-binding is an honour system when the domain is public and the token is public.

The proof: possession of a publicly-trusted certificate for the licensed domain. An honest estate already holds one; SHC provisions it over ACME as a matter of course, so nothing is asked of the customer. A pirate cannot get one, because a public CA will not issue for a domain they do not control. The certificate is therefore a proof of domain control that is free for the honest party and fatal to the attack.

Four things are checked (modules/license/dns_cert.go), and each earns its place:

checkwhy
chains to a public root, against a bare x509.SystemCertPool()the daemon has pool-augmenting helpers (keycloak_trust, edge_ca_pool) and either would make the check pass on exactly the estates it must fail; an estate can mint itself a leaf for any name
SAN covers the domain, via x509.Verify’s DNSNameapplies the normal wildcard rules, so a *.acme.com estate proves cloud.acme.com; a hostname-keyed map would miss it, and wildcard issuance is a supported posture
currently valid, via CurrentTimean expired certificate is not a present-tense proof
ExtKeyUsageServerAuthan unrelated client or e-mail leaf carrying the name cannot stand in

It must be LOCAL POSSESSION, not a dial. The cheap version (open a TLS connection to the licensed domain and inspect the certificate) is worthless and looks equivalent, which is why it is called out here. Dialling castclaws.com:443 reaches the victim’s server, which of course presents a good certificate; the pirate passes. What has to be proven is that this estate holds the material, so the check reads chains off this node’s own disk (traefik’s ACME store, plus certbroker’s delivered fullchain.pem) and verifies them.

An unwired prover REFUSES. “The check is not installed” must not be a way past the check, or an attacker’s first move is to arrange for it to be missing. Nodes that genuinely cannot read the store (swarm, non-ingress, pre-ACME) do not honour a DNS licence directly; they receive the estate’s licence the way they always have.

It never bricks. A failed proof means the DNS licence is not honoured and the estate falls through to whatever installed or broker licence it holds, exactly as if no record existed. The operator gets X403044LICCRT in shc license status naming which proof is missing: no certificate at all, a certificate for another name, or one from a private/staging CA are three different sentences because they have three different fixes.

3.2 THE CARRIER SPLIT, and why the file path is exempt

Section titled “3.2 THE CARRIER SPLIT, and why the file path is exempt”
DNS carrierfile install
token published?yes, world-readable in the zoneno, never leaves the estate
cert proofREQUIREDnot required
unbound token (* / empty)REFUSED (§3.3)accepted
audienceinternet-facing estatesairgap, lab, vendor fleet, zones you do not control

The exemption is not a concession, it is the same reasoning applied to a different fact pattern. There is nothing to harvest from an installed token, so there is no attack to close, and requiring a public certificate would break the deployment the file carrier exists for, since an airgapped estate has no public certificate by definition. The asymmetry tracks publication, which is the thing that actually changed.

3.3 Unbound tokens are refused from DNS (review finding F2)

Section titled “3.3 Unbound tokens are refused from DNS (review finding F2)”

An unbound licence (empty domains, or a sole "*") matches every domain by construction. That is right for the vendor fleet blanket installed on the vendor’s own machines and catastrophic in a public record: one leaked blanket would self-license any estate at any domain, straight past the domain match the whole carrier rests on. mint --dns already refused to emit one; that guard only binds the vendor’s own tooling, so the read path refuses one too, on both the live and cached legs (X403043LICUNB). install still accepts them; see the split above.

4. The account binding lives in the ledger, not the estate

Section titled “4. The account binding lives in the ledger, not the estate”

The token carries an optional account field: the vendor ledger subject the grant was sold to. It is display and support correlation only; nothing in the binary gates on it, exactly as nothing gates on type.

That is deliberate. An estate can only ever answer three questions: is this token signed by a key I trust, is it for my domain, and is it in date. Questions about the commercial relationship (is this account in good standing, how many concurrent domains has it been sold) are answered where the vendor mints, because that is the only place with the facts. Putting a domain count in the token would be an unverifiable claim the estate has no way to check and every incentive to ignore.

Adding the field did not bump FormatVersion, and that is not an oversight of the rule in license.go. The rule exists because the signature covers the payload BYTES, so a change that altered those bytes for an existing licence would invalidate it. omitempty is what makes this change not that: a licence minted without an account marshals byte-identically to before the field existed, so every licence in the field keeps verifying. In the other direction decodePayload’s decoder ignores unknown keys, so an older binary reads a token carrying one and simply does not see it, correct behaviour for a field nothing gates on. A bump would have refused every licence already issued.

5. Precedence: the strongest valid token wins

Section titled “5. Precedence: the strongest valid token wins”

An estate may hold both an installed token and a licence record. The rule is not carrier-based:

The estate runs the STRONGER of the two, by the supersession ladder two licence files already use: later expiry wins; a perpetual beats a dated one; an equal term is broken by the later mint instant; an exact tie is broken only by granting strictly more.

strongerLicence is literally newerLicense || richerSameTerm, the existing functions, not a reimplementation. A carrier-based rule (“DNS always wins”, “the file always wins”) would be a second ordering to keep in sync with the first, and would make one carrier a downgrade attack on the other.

shc license status reports which carrier is in force as source: dns / source: file.

6. What DNS is not allowed to do: take a licence away

Section titled “6. What DNS is not allowed to do: take a licence away”

A resolver outage, a registrar migration or a mistyped zone edit must never unlicense a running estate. So the last token that resolved and verified is cached on disk (license-dns.json, beside the licence token) and keeps resolving. The cache is bounded two ways and both bounds matter:

  1. The token’s own expiry, which degrades the estate exactly as an expired file does: growth refused, running workloads untouched, renewal wording intact, 14-day grace before the strong lock. No brick.
  2. DNSGraceDuration (14 days, the same constant as the lapse grace) since the last successful resolution, after which the cached copy stops being honoured at all.

Bound (2) is what keeps the carrier honest. Without it, a token that resolved once would license the estate until its expiry no matter what the zone said afterwards; “remove the record” would mean nothing.

Two failure directions are deliberate and worth naming:

  • A token that fails signature or domain verification is never cached. A forgery must not earn a grace window.
  • A record that is found and refused leaves an operator-facing note (X403042LICZON, surfaced in shc license status). The commonest field failure here is silent by construction (a record pasted from another estate’s zone, or a truncated value), and an estate that is quietly unlicensed for no visible reason is the worst outcome available.

6.1 Two clock-rollback holes, found by the tests

Section titled “6.1 Two clock-rollback holes, found by the tests”

Both bounds above are measured as now - <recorded instant>, and both were initially wrong in the same way: the subtraction goes negative when the clock moves backwards, a negative age is trivially “fresh”, and the check can then never be crossed. Winding a clock forward once and back again would have pinned the memo and made the cache permanent.

  • The memo now falls through when the age is negative; a clock that moved backwards is precisely when a re-resolve is wanted.
  • The cache re-stamps a future resolved_at to now and persists it. Clamping the age to zero was tried first and has the identical defect: the stamp never moves, so every later pass recomputes a negative age and clamps again. Re-stamping restarts the fourteen days from the correction, so a legitimate clock fix costs at most one extra window and the trick costs one window per rollback rather than an unbounded extension.

Anyone who can set the estate’s clock is root on the box and could patch the binary, so the bar here is “not free”, not “impossible”. Pinned by TestDNSCacheGraceSurvivesAClockRollback.

6.2 The Keycloak SPI reads a mirror (review finding F3)

Section titled “6.2 The Keycloak SPI reads a mirror (review finding F3)”

The SPI is the estate’s other licence consumer and the first cut left it out of the design entirely. It reads license.lic + estate-domain.json from the mounted licence directory and has no DNS rung, and cannot cheaply have one, since it would need the resolver, the supersession ladder and the certificate proof, in Java, on a separate release clock. On an estate keyed only by its record the SPI read nothing, resolved INDETERMINATE, and applied the free seat cap while the daemon was happily keyed. That is daemon-vs-SPI disagreement about one licence (the exact class of bug the estate-domain materialisation was built to end), and it would have surfaced as Keycloak quietly dropping to free limits weeks after a working install.

So a DNS-licensed daemon mirrors the token into the installed slot (materialiseDNSForSPI), refreshed on every Reverify from the live answer. Three properties make the mirror safe rather than a second grant:

  • It never outlives its record. The moment the DNS carrier stops producing a licence (record withdrawn, grace bound closed, proof failed) the mirror is deleted on the same pass.
  • It never touches an operator’s file. Deletion happens only when the bytes in the slot are byte-identical to the token this node recorded as its own mirror (in the DNS cache sidecar, so it survives restarts).
  • It is never published to the replicated row. The row is the estate’s durable “we hold this licence” and every node materialises from it, so a mirror pushed there would turn a deleted TXT record into a permanent grant across the cluster.

status still reports source: dns. The mirror is a rendering of the record, not a carrier, and calling it file would hide that removing the record ends the licence.

Section titled “6.3 Delink releases the estate; only removing the record releases the grant”

shc license delink drops the local files, tombstones the replicated row and drops the cached DNS token; leaving the cache would make delink a lie for up to the full grace window.

It deliberately does not stop the record from re-licensing the estate on the next resolve, and it must not pretend to. The zone is the customer’s and the record is the grant: an estate whose zone still says “licensed” is licensed, and a local veto over a signed grant would be a second source of truth in the one place licensing must not have one. So the CLI says so; a delink that leaves the estate keyed by DNS prints the record name and tells the operator to remove it. Pinned by TestDelinkDropsTheCachedDNSLicence and TestDelinkWithTheRecordStillPublishedReLicenses.

Offline verification and revocation lists are mutually exclusive; pubkey.go already says the same thing about key rotation. A DNS-carried licence is revoked the way every licence in this product is revoked: it runs out. What DNS adds is that the vendor can decline to mint the next one and the customer’s own zone stops carrying the old one, so the practical revocation lever is the term length and terms should be sized accordingly. This is not a weakening; it is the same lever a file licence has, plus one.

7. Why terraform computes the record but does not create it

Section titled “7. Why terraform computes the record but does not create it”

modules/license-dns emits the record (name, type, TTL, whole value, 255-byte chunks, zone-file line) and creates nothing. Three reasons, the first being the load-bearing one:

  1. The licence carrier must not be the licensed daemon’s to delete. SHC has a managed-DNS path (shc_dns_record, served by the daemon’s own DNS module) and routing the licence record through it would look natural. That module owns what it creates: companion ownership TXT rows, sweeps at managed hosts, an orphan reaper. Putting the licence inside that blast radius means a daemon bug, a release retry or a teardown can remove the record that licenses it, and the failure surfaces a fortnight later as an estate that lapsed for no visible reason. Separation of duties: the operator’s IaC writes it, the daemon only ever reads it.
  2. shc_dns_record cannot express it anyway; it classifies target into A / AAAA / CNAME and has no TXT on the surface.
  3. A zone is often not the cluster module’s to touch, and hard-wiring one cloud’s DNS provider would be wrong for every estate whose zone lives elsewhere and unusable for the airgapped case.

The module therefore declares no providers, so it composes with hetznerdns, cloudflare, aws, google, azurerm or plain RFC2136.

license_dns_token also installs the token via shc_license, and the redundancy is deliberate: worker joins cannot wait on a DNS TTL, because clustering is Pro-and-up and an unentitled join is refused X403029LICENT. Installing puts the entitlement on the graph edge where it is needed; the record is what keeps renewing afterwards without another apply. Same bytes, so they cannot disagree.

8. Deprecation posture for the older registration paths

Section titled “8. Deprecation posture for the older registration paths”

Per the ruling, no other registration mechanisms, but documented, not deleted:

pathstatuswhy it is still here
shc license activate --broker / ActivateOnline + the /.well-known/shc-license-challenge endpointsuperseded; help text says soin-flight estates registered this way; the challenge endpoint exists only to serve that callback and deprecates with it
shc license register <code>superseded; help text says soits case (private-network, lab, airgapped) is exactly what the record serves better, but an enrollment code that stops being redeemable strands a customer mid-provision
shc license refresh / MaybeRefresh (broker re-fetch)KEPT, not registrationthis is renewal delivery. A DNS-carried licence renews by the record changing, but an estate registered through the broker still renews by asking it. Retiring the verbs above must follow the estates, not lead them
shc license activate <file>kept, aliasedinstall is the better spelling and takes a bare token; activate stays for compatibility

Nothing new should be built on the superseded paths. They come out once the registered population is migrated to records.

9. Open policy question (deliberately not decided here)

Section titled “9. Open policy question (deliberately not decided here)”

Concurrent domains per purchase. The token binds one domain (or several, if minted so). How many concurrent domains a single purchase may carry, and whether a customer may move a licence between domains without a re-mint, is a LEDGER policy: the estate cannot verify it and must not try. It is recorded here as open rather than answered by implementation. activation_limit already exists in the payload and is advisory in the offline binary.

whatwhere
the DNS rung, cache, grace, precedencemodules/license/dns.go
wired into the posture rebuildmodules/license/service.go (Reverify)
carrier provenancemodules/license/resolver.go (Source)
security corpusmodules/license/dns_test.go, dns_mint_test.go
vendor mint modemodules/license/mint_cmd.go (--dns, --account)
fallback carrier verbmodules/license/commands.go (install)
kill switchlicense.dns_enabled (config_keys.go, wired in daemon/wiring/license_wire.go)
record computationterraform/modules/license-dns/
the terraform variablelicense_dns_token on modules/core and modules/shc/hetzner

11. What the adversarial review found, and where each finding landed

Section titled “11. What the adversarial review found, and where each finding landed”
#findingdisposition
F1HIGH: a public token + an operator-asserted domain + no proof of control = universal freeload (the pirate points SHC_HOST at the victim’s domain)FIXED: the cert proof, §3.1. Pinned by TestPirateAtVictimDomainIsRefused / TestHonestEstatePassesWithItsOwnCert
F2an unbound token is a skeleton key and nothing on the read side refused oneFIXED: §3.3, X403043LICUNB, refused on both legs; install still accepts (TestDNSRefusesAnUnboundToken, TestInstallStillAcceptsAnUnboundToken)
F3a DNS-only estate silently unlicenses Keycloak (the SPI has no DNS rung)FIXED: the SPI mirror, §6.2 (TestDNSLicenceIsMirroredForTheSPI, TestTheMirrorIsRemovedWhenTheRecordGoes, TestTheMirrorNeverOverwritesAnInstalledLicence)
F4the memo was not domain-keyed, so a live domain change served a licence resolved for the old oneFIXED: memo keyed on the normalised domain
F5”the spent cache is DELETED” was unproven; removing the delete left the suite greenFIXED: the grace test now stats the file
F6sanitizeTXTValue could be replaced with the identity functionFIXED: TestSanitizeTXTValueStripsZoneToolingNoise + an end-to-end quoted-record case
F7”strongest record wins” passed with a “last wins” mutantFIXED: the rotation test runs both RR orders
F8~18 pre-existing tests silently began making real LookupTXT callsFIXED: package TestMain installs a refusing default resolver through one seam (defaultTXTLookup)
F9two tests asserted only “not keyed” and would pass with the carrier disabledFIXED: both gained positive controls

The review also recorded a proof of absence for chunk-rejoin ambiguity, multi-record downgrade, forged signatures, unknown-key injection, row/file isolation, clock rollback, and the terraform surface. Those arguments still hold and were not disturbed by this amendment.

12. Review checklist for whoever takes §0

Section titled “12. Review checklist for whoever takes §0”
  • The domain wall: dns_test.go:TestDNSTokenForAnotherDomainRefused is the castclaws-token-on-bitspur case. Confirm nothing downstream of it can adopt a token whose domains do not cover the estate.
  • The cache: confirm nothing writes license-dns.json before VerifyForDomain returns nil error.
  • The grace bound: confirm a spent cache is deleted rather than merely ignored, so it cannot be resurrected by a clock change.
  • Isolation: confirm the DNS token never reaches the replicated licence row (TestDNSTokenIsNeverPublishedToTheEstateRow) nor the installed-file slot.
  • The Account field: confirm the no-bump reasoning in §4 against format.go, and that no gate reads it.
  • The memo: confirm dnsResolveInterval actually bounds gate-miss lookups (TestDNSLookupIsNotRepeatedOnEveryResolve), since Reverify is on the gate-miss path.
  • The clock bounds (§6.1): both were wrong on the first pass and only one test caught them. Look for any OTHER now.Sub(...) in this feature that decides whether something is still valid.
  • The cert proof is the load-bearing wall now. Confirm the trust pool is the bare system pool at every call site, that no path can reach a passing verdict with an unwired prover, and that the proof gates the DNS carrier ONLY; an installed or broker licence must be unaffected by it.
  • The mirror. Confirm it cannot outlive its record, cannot overwrite a file this node did not write, and never reaches the replicated row.