DNS challenge is in staging


@jmhodges and others in this thread who have working dns-01 tools:

For those of us who want to write a simple dns-01 client (or modify an existing acme client) to use dns-01 challenges, where can we see documentation about what the boulder API specifically for dns-01 challenges?

Based on how the official client works for http, I assume we’d just create a TXT record whose name is the same as the.well-known/acme-challenge/ file name, and whose TXT value is the same as the contents of that file. Before working on a client it would be great to understand how the boulder API works under the hood.

I looked in the Boulder repo, and all I could find is a high-level workflow design, and the api itself isn’t really self-documenting. Just curious if anybody has seen any good documentation or other resources that provide details about how the boulder API works: what it consumes, what it returns, and what to do with the response(s)?

I would reverse engineer one of the projects in this thread that claims to have dns-01 support, but I’m a sysadmin not a software developer…so Go and .net are out of my reach. I want to do it in .py.

I am looking at @sahsanu 's .sh client to see if that helps, but really any official/unofficial API docs for boulder would be most helpful.

Thanks all. This is a fantastic feature of a fantastic project. I think most tools will end up using dns-01 and an API based DNS provider like route53 as opposed to filesystem/http-01 based auth.


Boulder is a server implementation of the ACME spec, which should describe what you’re looking for.


thanks. I see my assumption was actually incorrect slightly. We create a TXT record for _acme-challenge.example.com with the digest value under that name. Like:

_acme-challenge.example.com. 300 IN TXT “gfj9Xq…Rg85nM”

thanks @pfg, this is exactly the set of docs I was looking for.


I tested dns-01 successfully on 06/01 using a modified acme-tiny and TXT records with a 1s TTL.


does the DNS challenge propagate to subdomains?
so when I want a cert for example.com, a.exmple.com and .b.example.com that I would just need to set a record in example.com?


Seems to be working quite nicely for me with letsencrypt.sh with one of my domains, but having trouble getting one of the others to work. Still trying to determine why - it just gets ‘invalid’ ever time.


I hope not. Think about the implications.


why? what’s the problem with it. using the PSL /which actually is already used for ratelimiting( as a base so the TLDs cannot do anything themselves, also any provider with DNS control can manually set all the records so I dint see the problem.


When I think of DNS delegation, I think about that subdomain being under a different administrative control. If a.example.com is delegated elsewhere, example.com shouldn’t “silently” or just “accidentally” have the ability to issue certs for a.example.com.

Also, it feels like a sloppy play with semantics. If you want a cert for a.example.com, you should have to prove control over a.example.com directly. I wouldn’t be surprised if this is already regulated somewhere. IMO, you shouldn’t start playing games where you issue certs without really checking ownership, because usually these shortcuts lead to a weakness in some obscure setup down the road.


well most CAs confirm the root by the whois email or the administraive mail addresses, and there you cant do subs. also if you control the DNS (e.g. dyndns provider) they can get a cert over that domain. but if you get a subdomain for a domain you dont even own then it’s obvious you dont have the freedom as with a root domain.


BTW, does the LE server follow CNAMEs? Then it would be trivial to add references from each subdomain’s challenge to the parent domain’s challenge, thereby expressing explicit intent that example.com should be able to answer challenges for a.example.com.

Implicit behaviour just feels wrong when dealing with such delicate processes.


Let’s Encrypt follows CNAMEs.

We follow the ACME spec. If you want changes to how Let’s Encrypt does validation, propose the change to the IETF github repo.


Perfect. Then where is the problem?

_acme-challenge.a.example.com. IN CNAME _acme-challenge.example.com.
_acme-challenge.b.example.com. IN CNAME _acme-challenge.example.com.

And then you only have to update _acme-challenge.example.com.

This way you’re explicitly saying that a.example.com is “aware” of incoming ACME challenges and where those challenges should be handled. No behaviour is implied on LE’s part that would definitely confuse someone down the road.


@TCM from the tests I run, each challenge has an unique token. Therefore, you can’t really point the _acme-challenge for a and b to a single _acme-challenge.example.com record, because the token is not the same.

I run into the first time I tried to issue a certificate for example.com and www.example.com. I mistakenly assumed that the validation for www.example.com would be implicit after validating example.com, or that I could reuse the same toke, but I was wrong.

I had to create 2 different DNS records, each one with the corresponding token returned by LE.

In order to accomplish what you propose, LE should not return a different token for all the subdomains of a given suffix. But as far as I understood, this is not what’s happening today.


I see. So it would only be usable if you want to create single-name certs for a bunch of different names but don’t want to create dozens of different subdomains that all need to be updateable.

You could direct those names to a central subdomain that is allowed to be updated and disable updates for the real names as should be the default.


I don’t understand why you can’t just have the challenge on the main domain. If you control the main domain, you control all subdomains, its just how DNS is designed.


that wouldn’t work very well for people on dyndns domain for example though, where I may have serverco.dyndns.org ( I don’t really - just an example) and want an SSL cert for my account on that.


Why not? You would obviously walk the hierarchy for validation. If you control the root domain, all fine, if you control a subdomain, also fine.


I don’t control dyndns.org ( a dynamic dns provider a lot of people use ), I only control my single sub-domain.


And? Maybe I was not clear enough:
If the token is at the root you can create certificates for the root and all subdomains.
If the token is at the subdomain you can create certificates for all subdomains starting at your subdomain.