Let’s Encrypt Wildcard Certificates

Let’s Encrypt Wildcard Certificates have been possible for a few months as well and I am really enthusiastic about it and so should you. There are however some setup rules and limitations you need to keep in mind.


General setup is the same as for any other Let’s Encrypt Setup. I wrote about LE and setups here and here. It can be done with certbot or another form built into your app. There are many packages for this around. Just make sure the work with the second generation API (ACME v2). The link to packages here mentions the ones that do. If you use one that works with ACME v1 wildcard DNS is not possible!

Wildcard DNS Validation

Let’s Encrypt Wildcard Certificates however only work with DNS-01 validation, not a challenge as for standard domain names, so you need to be able to add a DNS txt record to your DNS for the domain in question. And that makes it different from the other setups for single domains.

Certbot DNS Plugin

The DNS Plugin Certbot needs is not available for all OS yet so do check at Certbot. this may mean you need to run Docker on your OS or use something else than certbot-auto. Even installing the general plugin like on Nginx with a Unix OS not on the list: https://certbot.eff.org/lets-encrypt/pip-nginx won’t get you to do the DNS part yet.

Rate Limitations

There are general rate limitations on LE usage:

  • The main limit is Certificates per Registered Domain, (50 per week)*.
  • If you have a lot of subdomains, you may want to combine them into a single certificate, up to a limit of 100 Names per Certificate**.
  • You can create a maximum of 10 Accounts per IP Address per 3 hours
  • New Orders per Account. For the production ACME v2 endpoint one account may not exceed 300 new orders per 3 hours****
  • You can have a maximum of 300 Pending Authorizations on your account.

* For a user creating many subdomains this would be an issue.
**If you need to support older clients like Windows XP that do not support TLS Server Name Indication (SNI), you’ll need a unique IP address for every certificate, so putting more names on each certificate reduces the number of IP addresses you’ll need.
****So if for a single account (useful for large hosters) you could hit this limit though upgrades are possible as you can read later on.

One account or Many?

One account per domain or user may be good, especially if you want to avoid a full across the board domain certificate compromise due to the contamination of one account, but for large parties one single account is often better for identification and limit adjustments (see also next header block):

.. most larger hosting providers we recommend using a single account and guarding the corresponding account key well. This makes it easier to identify certificates belonging to the same entity, easier to keep contact information up-to-date, and easier to provide rate limits adjustments if needed. We will be unable to effectively adjust rate limits if many different accounts are used.

Also due to the account limit per ip address I would assume most large parties would prefer one account as well. Just to avoid this limit.

Rate Limit Bypass

If you are a large hosting provider you can bypass them by making a request:

If you are a large hosting provider or organization working on a Let’s Encrypt integration, we have a rate limiting form that can be used to request a higher rate limit. 

Well, that will not be the case for the most of us of course..

Wildcard Domain Name Rate Limitations

These rate limitations should however not apply to one single wildcard domain for one FQDN (Fully Qualified Domain Name like imwz.io ). So you should be able to generate as many subdomains using that one wildcard domain as you would like.

Automated Generation Wildcard

If you want the adding of the DNS Text domain for validation by Let’s Encrypt automated your domain hoster needs to have an API to take care of this. Laravel Forge has Route53, Digital Ocean and Cloudflare’s API’s built in. See blog post of Taylor on this . Very convenient. Only you cannot do it manually if you do not want to use one of these three parties. And that is a major bummer for a lot of us.

Automated generation is convenient and often used by larger hosters. Do remember earlier remarks on using one account vs multiple and the order limit per account.

Manual Generation Wildcard w/ Certbot

If you cannot use an API to generate the LE wildcard wildcard certificate and deal with the DNS-01 challenge you will have to do it all manually. With Certbot you can (if your OS can run it including DNS plugin as mentioned earlier!). Saurabh explains it really well using certbot.

The actual command for generating the certificate is:

/certbot-auto certonly \
--server https://acme-v02.api.letsencrypt.org/directory \
--manual \
--email you@example.com \
--preferred-challenges dns \
-d  *.example.com

Once that is done you still need to create the DNS txt file with the name and value as suggested by Certbot. Once that is done the check can be made and wildcard domain verified.

Certbot in Docker

If your OS does not support Certbot yet nor the DNS plugin there is a Docker option. But this certainly makes your life a lot more complicated!

Certificate Generation w/ Library

There are some libraries out there that do general certificate generation as well as wildcard ones with DNS-01 verification. Stonemax ACME2 is one of them for us PHP people. And there are others. If you cannot run Certbot nor DNS Plugin nor want to go for Docker go through them.

Jasper Frumau

Jasper has been working with web frameworks and applications such as Laravel, Magento and his favorite CMS WordPress including Roots Trellis and Sage for more than a decade. He helps customers with web design and online marketing. Services provided are web design, ecommerce, SEO, content marketing. When Jasper is not coding, marketing a website, reading about the web or dreaming the internet of things he plays with his son, travels or run a few blocks.