Wildcard certificates with Let’s Encrypt

For the past months, I’ve been relying on Let’s Encrypt to secure my domain with a free SSL certificate. The setup is fairly easy and to me, they provide an invaluable service. Recently, Let’s Encrypt has announced support for wildcard certificates which makes the life of system administrators even easier.

What are wildcard certificates about?

In the past you’ve already been able to add several domain names and subdomains to your certificate, like effenberger.org, www.effenberger.org, mail.effenberger.org. However, adding or removing a subdomain always required creating a new certificate, which was tedious and didn’t scale so well, not talking about the rate limits that could have hit you.

Wildcard certificates make your life much easier by allowing domains like *.effenberger.org, which covers everything under the first level of the respective domain. Second-level names like backup.mail.effenberger.org are rather not covered, but likely require *.*.effenberger.org as wildcard, but I’ve not tested this yet.

Installing the client

First of all, you need to install a compatible Let’s Encrypt client.  The official one can be installed via

git clone https://github.com/letsencrypt/letsencrypt

Afterwards, several Python packages might need installing. To invoke that process, start the client once with

letsencrypt/letsencrypt-auto --help

and provide your credentials for sudo, as the system-wide installation requires root privileges. The client will invoke your distribution’s package managers to provide for the missing files.

DNS challenge validation

In a second step you create the actual SSL certificate, which requires validation of the domain. There are various ways to proof ownership of the domain you’re requesting a certificate for. In order to get wildcard certificates, the DNS challenge validation is a requirement. For that, you need access to your domain’s nameserver entries and create a TXT record. If you’re unsure what this is about, you’re better off asking your provider or system administrator, as you can easily break your website with a misconfigured DNS.

To get the require challenge, invoke the following command

letsencrypt/letsencrypt-auto certonly --manual --preferred-challenges dns --server https://acme-v02.api.letsencrypt.org/directory --email your.mail@address --domains *.your.domain

and replace your.mail@address with your e-mail address and *.your.domain with the domain name you wish to get a SSL certificate for, respectively.

You might be asked to accept the terms of service and agree to your IP address being logged. You might also be asked whether you want to share your e-mail address with EFF.

Afterwards, the challenge is shown:

Please deploy a DNS TXT record under the name
_acme-challenge.your.domain with the following value:

123a3aBxz1tLPow0x7J3BL8Dj9atPkO3rjDo9J-PAtl

You have to add the following line to your DNS zone file, replacing the last string with what the client shows you:

_acme-challenge IN TXT 123a3aBxz1tLPow0x7J3BL8Dj9atPkO3rjDo9J-PAtl

Please wait a few minutes after you have done that, for the DNS records to deploy, and then press Enter.

Using the certificate

The Let’s Encrypt client now tries to verify the domain. If all went well, the new certificate resides in /etc/letsencrypt/live/your.domain and can be included in your mail, web and other application server.

Don’t forget to renew it in due time, as wildcard certificates last 90 days, just like any other Let’s Encrypt certificate.

Thanks to the nice folks at Let’s Encrypt for the new wildcard functionality – you rock!