Add support for the draft dns-persist-01 challenge by beautifulentropy · Pull Request #536 · letsencrypt/pebble

beautifulentropy · 2026-02-10T21:47:34Z

Adds support for draft specification of the dns-perist-01 ACME challenge type.

Draft specification can be found here and the BRs text covering this challenge can be found here.

mcpherrinm · 2026-02-10T22:16:22Z

re: linter failure, let's disable the perfsprint linter? Pebble isn't super perf-sensitive and on 1.26.0, fmt.Errorf is equivalent

va/va_test.go

beautifulentropy · 2026-02-12T17:59:21Z

va/va.go

+// trimWSP trims RFC 8659 whitespace characters (space and tab) from the
+// beginning and end of a string.
+func trimWSP(s string) string {
+	return strings.TrimFunc(s, func(r rune) bool {
+		return r == ' ' || r == '\t'
+	})
+}
+
+// splitIssuerDomainName splits an RFC 8659 issue-value into issuer-domain-name
+// and raw parameter segments. It returns zero values when issuer-domain-name is
+// missing.
+func splitIssuerDomainName(raw string) (string, []string) {
+	// Split into issuer-domain-name and parameters.
+	parts := strings.Split(raw, ";")
+	if len(parts) == 0 {
+		return "", nil
+	}
+	// Parse issuer-domain-name.
+	issuerDomainName := trimWSP(parts[0])
+	if issuerDomainName == "" {
+		return "", nil
+	}
+	return issuerDomainName, parts[1:]
+}


I don't love splitting these two functions like this, but I'm not seeing a better way to peek at the issuer-domain-name, without performing a second split. So, it feels like if we're going to split we might as well return the issuer-domain-name string and the remainder []string. That way we don't have to do that work again. Let me know if you have other alternatives.

…rt-part-2

jsha

Some optional nits; otherwise good.

va/va.go

jsha · 2026-02-13T00:15:45Z

va/va.go

+			// We know if this record was intended for us but it is malformed,
+			// we can continue checking other records but we should report the
+			// syntax error if no other record authorizes the challenge.


Checking the spec, it seems not fully specified whether a CA should ignore malformed records that are intended for it.

Closest seems to be:

4.1.1. Coexistence of Records
When multiple TXT records are present at the same DNS label (e.g., _validation-persist.example.com), each record functions as an independent authorization for the specified issuer. This follows a similar pattern to CAA records [RFC8659], where multiple records at the same label are permissible.

But honestly I think it would be better to just error on any malformed record that has your issuer; or maybe any malformed record at all. I'll file an issue on the spec. Let's keep the behavior here as-is, pending any spec changes.

Considering those statements:

Validate Record: If a matching record is found, the CA proceeds to validate it according to the requirements in this specification, including verifying the accounturi and persistUntil parameters.

CAs SHOULD return a malformed error (as defined in [RFC8555]) when the TXT record has invalid syntax, such as duplicate parameters, invalid timestamp format in the persistUntil parameter, missing mandatory accounturi parameter, or other syntactic violations of the record format specified in this document.

I would read that as "all intended records are validated", but you are right that it isn't clear what to do then.

It is a bigger question with regards to how multiple records that are intended for the same CA are handled,
like if there are two records that are applicable, one is expired and other is not, then expired one should be ignored logically,
if there is a wildcard record and a record that isn't a wildcard then for wildcard validation only one of them is applicable,
or there could be two records with different account urls,
and probably doing the same with malformed records just for consistency makes sense.

or there could be two records with different account urls

In particular this is an important use case to allow in my opinion.

kanashimia

I verified that it works on my client, code overall seems okay.

As it seems to me there is no just in time validation as described in https://datatracker.ietf.org/doc/html/draft-ietf-acme-dns-persist#name-just-in-time-validation, returning status doesn't seem to be set to "valid".
It is optional, maybe makes sense to implement it too?
For context I relied on it in my client to not print "please set this DNS record to the following value" logs when DNS record is already validated.

kanashimia · 2026-02-13T11:53:57Z

Just an observation but when there are multiple? records for same CA and one? of them is invalid, for example when uri is wrong,
it errors like challenge error: "Error retrieving TXT records for DNS-PERSIST-01 challenge: dns: overflowing header size" (urn:ietf:params:acme:error:unauthorized) (HTTP status code 200) Aborting.
That overflowing header size error message is pretty weird, should be more descriptive.
That seems to be an error coming from miekg/dns, weird.

beautifulentropy · 2026-02-14T00:21:14Z

Just an observation but when there are multiple? records for same CA and one? of them is invalid, for example when uri is wrong,

it errors like challenge error: "Error retrieving TXT records for DNS-PERSIST-01 challenge: dns: overflowing header size" (urn:ietf:params:acme:error:unauthorized) (HTTP status code 200) Aborting.

That overflowing header size error message is pretty weird, should be more descriptive.

That seems to be an error coming from miekg/dns, weird.

This is very interesting! Wrong in what sense, syntax (malformed) or authorization?

kanashimia · 2026-02-14T06:13:53Z

This is very interesting! Wrong in what sense, syntax (malformed) or authorization?

Authorization, like if you add a dns record, then restart pebble without restarting dns server, so you add another record, now there are two records with different accounturis, but I think it may happen in other cases possibly.

kanashimia · 2026-02-14T09:44:13Z

Ahh, @beautifulentropy I think it is just because there is the same fixed sized buffer for all records and it overflows (not really an overflow in C sense, but I mean buffer is too small).
If I just add same record like 3 or more times there is similar error.
Also got the following errors like that too:
Error retrieving TXT records for DNS-PERSIST-01 challenge: dns: overflow unpacking uint16
and
Error retrieving TXT records for DNS-PERSIST-01 challenge: dns: buffer size too small
It seems specific error depends on what point it overflows at.

Ok, from what I see it is due to how miekg/dns handles requests, it seems like a pretty low level library, and it uses 512 UDP buffer by default, it doesn't retry over TCP or sets EDNS0 for you, so I think the solution here is retry over TCP or set Edns0 to a larger value, but I think retrying over TCP is better, it seems challtestsrv needs to be changed too, to include truncate flag.
Wait a bit, I will write a patch.

kanashimia · 2026-02-14T13:44:45Z

Ok, here is a patch, please test that there was a problem before and wasn't after applying:

Details

diff --git a/va/va.go b/va/va.go
index cfc7d51..3a1bbdc 100644
--- a/va/va.go
+++ b/va/va.go
@@ -111,6 +111,7 @@ type VAImpl struct {
 	strict             bool
 	customResolverAddr string
 	dnsClient          *dns.Client
+	dnsClientTCP       *dns.Client
 
 	// The VA having a DB client is indeed strange. This is only used to
 	// facilitate va.setOrderError changing the ARI related order replacement
@@ -139,6 +140,8 @@ func New(
 	if customResolverAddr != "" {
 		va.log.Printf("Using custom DNS resolver for ACME challenges: %s", customResolverAddr)
 		va.dnsClient = new(dns.Client)
+		va.dnsClientTCP = new(dns.Client)
+		va.dnsClientTCP.Net = "tcp"
 	} else {
 		va.log.Print("Using system DNS resolver for ACME challenges")
 	}
@@ -832,10 +835,20 @@ func (va VAImpl) getTXTEntry(name string) ([]string, error) {
 		return net.DefaultResolver.LookupTXT(ctx, name)
 	}
 
+	const dnssec = false
+	const udpMaxMsgSize uint16 = 1220 // should be small enough to not cause packet fragmentation
+
 	var txts []string
 	message := new(dns.Msg)
 	message.SetQuestion(dns.Fqdn(name), dns.TypeTXT)
+	message.SetEdns0(udpMaxMsgSize, dnssec)
 	in, _, err := va.dnsClient.ExchangeContext(ctx, message, va.customResolverAddr)
+
+	if in.Truncated {
+		// Response was truncated, retry over TCP instead
+		in, _, err = va.dnsClientTCP.ExchangeContext(ctx, message, va.customResolverAddr)
+	}
+
 	if err != nil {
 		return nil, err
 	}
diff --git a/vendor/github.com/letsencrypt/challtestsrv/dns.go b/vendor/github.com/letsencrypt/challtestsrv/dns.go
index 40c806e..5766eb1 100644
--- a/vendor/github.com/letsencrypt/challtestsrv/dns.go
+++ b/vendor/github.com/letsencrypt/challtestsrv/dns.go
@@ -398,7 +398,7 @@ func (s *ChallSrv) dohHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	s.dnsHandlerInner(&dnsToHTTPWriter{w}, msg, r.Header.Get("User-Agent"))
+	s.dnsHandlerInner(&dnsToHTTPWriter{w}, msg, r.Header.Get("User-Agent"), "http")
 }
 
 // dnsHandler is a miekg/dns handler that can process a dns.Msg request and
@@ -407,7 +407,7 @@ func (s *ChallSrv) dohHandler(w http.ResponseWriter, r *http.Request) {
 // records. A host that is aliased by a CNAME record will follow that alias
 // one level and return the requested record types for that alias' target
 func (s *ChallSrv) dnsHandler(w dns.ResponseWriter, r *dns.Msg) {
-	s.dnsHandlerInner(w, r, "")
+	s.dnsHandlerInner(w, r, "", w.LocalAddr().Network())
 }
 
 // newDefaultSOA returns a DNS SOA record with sensible default values.
@@ -428,7 +428,7 @@ func newDefaultSOA() *dns.SOA {
 	}
 }
 
-func (s *ChallSrv) dnsHandlerInner(w writeMsg, r *dns.Msg, userAgent string) {
+func (s *ChallSrv) dnsHandlerInner(w writeMsg, r *dns.Msg, userAgent string, proto string) {
 	m := new(dns.Msg)
 	m.SetReply(r)
 	m.Compress = false
@@ -482,6 +482,17 @@ func (s *ChallSrv) dnsHandlerInner(w writeMsg, r *dns.Msg, userAgent string) {
 	}
 
 	m.Ns = append(m.Ns, newDefaultSOA())
+
+	if proto == "udp" {
+		if opt := r.IsEdns0(); opt != nil {
+			m.Truncate(int(opt.UDPSize()))
+		} else {
+			m.Truncate(dns.MinMsgSize)
+		}
+	} else {
+		m.Truncate(dns.MaxMsgSize)
+	}
+
 	_ = w.WriteMsg(m)
 }

As that requires changes to multiple repos please apply yourself, I made it by modifying vendor dir so beware, thanks!

Also I don't know the reasoning behind Compress = false there but Truncate can set compression to true.
And may want to replace proto string with an actual enum or just a isUDP boolean, go stdlib uses stringly typed api for some unknown reason for net.Addr, so I just followed that....
Selecting buffer size is described in the Truncate docs: https://pkg.go.dev/github.com/miekg/dns#Msg.Truncate
I changed only this one specific function for querying TXT record, that probably need adjustment too.

EDIT: EDNS0 advertised udp buffer size shouldn't be used for TCP (duh) from what I understand, I updated the patch here.
Also I found that dig from bind can't set EDNS0 buf size larger than 32KB... Even though it mentions that max size is 64KB in the manpage... kdig from knot dns works like expected... each day I become more disappointed in literally everything.

This patch isn't really specific to dns-persist-01.

beautifulentropy · 2026-02-17T16:30:43Z

Ok, here is a patch, please test that there was a problem before and wasn't after applying:

Details

diff --git a/va/va.go b/va/va.go
index cfc7d51..3a1bbdc 100644
--- a/va/va.go
+++ b/va/va.go
@@ -111,6 +111,7 @@ type VAImpl struct {
 	strict             bool
 	customResolverAddr string
 	dnsClient          *dns.Client
+	dnsClientTCP       *dns.Client
 
 	// The VA having a DB client is indeed strange. This is only used to
 	// facilitate va.setOrderError changing the ARI related order replacement
@@ -139,6 +140,8 @@ func New(
 	if customResolverAddr != "" {
 		va.log.Printf("Using custom DNS resolver for ACME challenges: %s", customResolverAddr)
 		va.dnsClient = new(dns.Client)
+		va.dnsClientTCP = new(dns.Client)
+		va.dnsClientTCP.Net = "tcp"
 	} else {
 		va.log.Print("Using system DNS resolver for ACME challenges")
 	}
@@ -832,10 +835,20 @@ func (va VAImpl) getTXTEntry(name string) ([]string, error) {
 		return net.DefaultResolver.LookupTXT(ctx, name)
 	}
 
+	const dnssec = false
+	const udpMaxMsgSize uint16 = 1220 // should be small enough to not cause packet fragmentation
+
 	var txts []string
 	message := new(dns.Msg)
 	message.SetQuestion(dns.Fqdn(name), dns.TypeTXT)
+	message.SetEdns0(udpMaxMsgSize, dnssec)
 	in, _, err := va.dnsClient.ExchangeContext(ctx, message, va.customResolverAddr)
+
+	if in.Truncated {
+		// Response was truncated, retry over TCP instead
+		in, _, err = va.dnsClientTCP.ExchangeContext(ctx, message, va.customResolverAddr)
+	}
+
 	if err != nil {
 		return nil, err
 	}
diff --git a/vendor/github.com/letsencrypt/challtestsrv/dns.go b/vendor/github.com/letsencrypt/challtestsrv/dns.go
index 40c806e..5766eb1 100644
--- a/vendor/github.com/letsencrypt/challtestsrv/dns.go
+++ b/vendor/github.com/letsencrypt/challtestsrv/dns.go
@@ -398,7 +398,7 @@ func (s *ChallSrv) dohHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	s.dnsHandlerInner(&dnsToHTTPWriter{w}, msg, r.Header.Get("User-Agent"))
+	s.dnsHandlerInner(&dnsToHTTPWriter{w}, msg, r.Header.Get("User-Agent"), "http")
 }
 
 // dnsHandler is a miekg/dns handler that can process a dns.Msg request and
@@ -407,7 +407,7 @@ func (s *ChallSrv) dohHandler(w http.ResponseWriter, r *http.Request) {
 // records. A host that is aliased by a CNAME record will follow that alias
 // one level and return the requested record types for that alias' target
 func (s *ChallSrv) dnsHandler(w dns.ResponseWriter, r *dns.Msg) {
-	s.dnsHandlerInner(w, r, "")
+	s.dnsHandlerInner(w, r, "", w.LocalAddr().Network())
 }
 
 // newDefaultSOA returns a DNS SOA record with sensible default values.
@@ -428,7 +428,7 @@ func newDefaultSOA() *dns.SOA {
 	}
 }
 
-func (s *ChallSrv) dnsHandlerInner(w writeMsg, r *dns.Msg, userAgent string) {
+func (s *ChallSrv) dnsHandlerInner(w writeMsg, r *dns.Msg, userAgent string, proto string) {
 	m := new(dns.Msg)
 	m.SetReply(r)
 	m.Compress = false
@@ -482,6 +482,17 @@ func (s *ChallSrv) dnsHandlerInner(w writeMsg, r *dns.Msg, userAgent string) {
 	}
 
 	m.Ns = append(m.Ns, newDefaultSOA())
+
+	if proto == "udp" {
+		if opt := r.IsEdns0(); opt != nil {
+			m.Truncate(int(opt.UDPSize()))
+		} else {
+			m.Truncate(dns.MinMsgSize)
+		}
+	} else {
+		m.Truncate(dns.MaxMsgSize)
+	}
+
 	_ = w.WriteMsg(m)
 }

As that requires changes to multiple repos please apply yourself, I made it by modifying vendor dir so beware, thanks!

Also I don't know the reasoning behind Compress = false there but Truncate can set compression to true. And may want to replace proto string with an actual enum or just a isUDP boolean, go stdlib uses stringly typed api for some unknown reason for net.Addr, so I just followed that.... Selecting buffer size is described in the Truncate docs: https://pkg.go.dev/github.com/miekg/dns#Msg.Truncate I changed only this one specific function for querying TXT record, that probably need adjustment too.

EDIT: EDNS0 advertised udp buffer size shouldn't be used for TCP (duh) from what I understand, I updated the patch here. Also I found that dig from bind can't set EDNS0 buf size larger than 32KB... Even though it mentions that max size is 64KB in the manpage... kdig from knot dns works like expected... each day I become more disappointed in literally everything.

This patch isn't really specific to dns-persist-01.

Awesome, if you're open to it, we'd gladly accept a PR for this fix. I'd take the patch and post one myself but I'd rather you get the credit.

UDP buffer is only 512 bytes by default, it is pretty much never enough for the cases when there are multiple DNS records in a single response, so the responses are cut at arbitrary points which causes problems. This fixes that by truncating responses at record boundaries and setting TC bit, DNS clients should then read TC bit and retry over TCP which allows for a 64KB buffer. See docs: https://pkg.go.dev/github.com/miekg/dns#Msg.Truncate Was originally found in letsencrypt/pebble#536 (comment)

UDP buffer is only 512 bytes by default, it is pretty much never enough for the cases when there are multiple DNS records in a single response, so the responses are cut at arbitrary points which causes problems. This fixes that by truncating responses at record boundaries and setting TC bit, DNS clients should then read TC bit and retry over TCP which allows for a 64KB buffer. Truncate function also enables compression if message doesn't fit in the buffer uncompressed but fits if it is compressed. See docs: https://pkg.go.dev/github.com/miekg/dns#Msg.Truncate Was originally found in letsencrypt/pebble#536 (comment)

TXT records can be quite large, with is a problem for DNS challenges, they don't fit in the 512 buffer especially if there are multiple. DNS servers can increase the buffer size through EDNS0 extension, and retry over TCP if that wasn't enough. DNS server should truncate response if it doesn't fit in the buffer, and set TC (Truncate) bit, then DNS client should retry over TCP. 1220 value for UDP buffer size was chosen based on this recommendation: https://www.isc.org/blogs/dns-flag-day-2020-2/ This changes only TXT request, I left other methods untouched. But it would make sense to do the same logic for all requests, by building some small abstraction around miekg/dns for requests. Also see docs for Exchange function: https://pkg.go.dev/github.com/miekg/dns#Client.Exchange Was originally found in letsencrypt#536 (comment)

TXT records can be quite large, with is a problem for DNS challenges, they don't fit in the 512 buffer especially if there are multiple. DNS servers can increase the buffer size through EDNS0 extension, and retry over TCP if that wasn't enough. For the pebble puposes there isn't much reason to try UDP first, it is possible to just always query DNS records over TCP, so we do. Also see docs for Exchange function: https://pkg.go.dev/github.com/miekg/dns#Client.Exchange Was originally found in letsencrypt#536 (comment)

TXT records can be quite large, with is a problem for DNS challenges, they don't fit in the 512 buffer especially if there are multiple. DNS servers can increase the buffer size through EDNS0 extension, and retry over TCP if that wasn't enough. For the pebble purposes there isn't much reason to try UDP first, it is possible to just always query DNS records over TCP, so we do. Was originally found in letsencrypt#536 (comment)

beautifulentropy force-pushed the add-dns-persist-support-part-2 branch 8 times, most recently from 6facf40 to e16ebf7 Compare February 11, 2026 20:46

beautifulentropy marked this pull request as ready for review February 11, 2026 20:51

Add support for the draft dns-perist-01 challenge

bcf9af7

beautifulentropy force-pushed the add-dns-persist-support-part-2 branch from e16ebf7 to bcf9af7 Compare February 11, 2026 20:58

beautifulentropy requested a review from jsha February 11, 2026 20:58

beautifulentropy changed the title ~~Add support for the draft dns-perist-01 challenge~~ Add support for the draft dns-persist-01 challenge Feb 11, 2026

Small change to various validation errors

3e531d5

kanashimia reviewed Feb 12, 2026

View reviewed changes

va/va_test.go Outdated Show resolved Hide resolved

beautifulentropy requested a review from aarongable February 12, 2026 16:42

Fix validation comment and combine test cases

045521b

beautifulentropy requested a review from kanashimia February 12, 2026 17:27

beautifulentropy mentioned this pull request Feb 12, 2026

Fix go-lint-checks CI job failures #537

Merged

beautifulentropy commented Feb 12, 2026

View reviewed changes

beautifulentropy added 2 commits February 12, 2026 13:04

Merge remote-tracking branch 'origin/main' into add-dns-persist-suppo…

17ea930

…rt-part-2

Additional test case

02de36f

jsha approved these changes Feb 13, 2026

View reviewed changes

kanashimia reviewed Feb 13, 2026

View reviewed changes

beautifulentropy mentioned this pull request Feb 13, 2026

Specific case-Insensitivity carveout for the value of the policy tag ietf-wg-acme/draft-ietf-acme-dns-persist#34

Open

beautifulentropy merged commit d180fbf into main Feb 17, 2026
14 checks passed

beautifulentropy deleted the add-dns-persist-support-part-2 branch February 17, 2026 18:24

kanashimia mentioned this pull request Feb 17, 2026

Set truncate bit for DNS responses letsencrypt/challtestsrv#35

Open

kanashimia mentioned this pull request Feb 17, 2026

Always query DNS records over TCP instead of UDP #540

Merged

beautifulentropy added a commit that referenced this pull request Feb 17, 2026

Optional comments from #536

573cc4e

beautifulentropy mentioned this pull request Feb 17, 2026

Optional comments from #536 #541

Open

Conversation

beautifulentropy commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcpherrinm commented Feb 10, 2026

Uh oh!

Uh oh!

beautifulentropy Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsha left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jsha Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

kanashimia Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kanashimia left a comment

Choose a reason for hiding this comment

Uh oh!

kanashimia commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

beautifulentropy commented Feb 14, 2026

Uh oh!

kanashimia commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kanashimia commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kanashimia commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

beautifulentropy commented Feb 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

beautifulentropy commented Feb 10, 2026 •

edited

Loading

beautifulentropy Feb 12, 2026 •

edited

Loading

kanashimia Feb 13, 2026 •

edited

Loading

kanashimia commented Feb 13, 2026 •

edited

Loading

kanashimia commented Feb 14, 2026 •

edited

Loading

kanashimia commented Feb 14, 2026 •

edited

Loading

kanashimia commented Feb 14, 2026 •

edited

Loading