How to Get a Wildcard Domain DNS TLS Certificate from Let's Encrypt with certbot

PKI
How to Get a Wildcard Domain DNS TLS Certificate from Let's Encrypt with certbot

 

Page content

Let’s Encrypt is a free and open Certificate Authority that offers SSL/TLS certificates to secure web traffic. In addition to standard domain validation, Let’s Encrypt also supports wildcard domain validation, which allows you to secure all subdomains of a domain with a single certificate. In this tutorial, we’ll walk through the steps of obtaining a wildcard domain DNS TLS certificate from Let’s Encrypt.

Step 1: Prerequisites

Before we start, make sure you have the following prerequisites installed on your system:

  • Certbot: Let’s Encrypt provides an official client called Certbot for generating and renewing certificates. You can install Certbot on your system by following the instructions on the official - Certbot website: https://certbot.eff.org/
  • DNS Provider: You’ll need to have access to your DNS provider’s API key or account credentials, as we’ll be using DNS validation to obtain the wildcard certificate. Make sure your DNS provider is one of the supported providers by Certbot, which you can find on the following link: https://certbot.eff.org/docs/using.html#dns-plugins

Install CertBot on Mac

Run following command on the command line on the machine to install Certbot on Mac:

brew install certbot

Install CertBot on Debian 10

Run following command on the command line on the machine to install Certbot on Debian.

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

Step 2: Generate the Wildcard Domain DNS TLS Certificate

Once you have Certbot installed and your DNS provider credentials, you can use the following command to obtain the wildcard domain DNS TLS certificate:

sudo certbot certonly --dns-<dns-provider> --dns-<dns-provider>-credentials /path/to/credentials/file -d '*.example.com' -d example.com --preferred-challenges dns-01

Make sure to replace <dns-provider> with the name of your DNS provider and /path/to/credentials/file with the path to the credentials file for your DNS provider.

The -d option specifies the domain names for which you want to obtain the certificate. In this case, we’re obtaining a wildcard certificate for all subdomains of example.com.

The --preferred-challenges option tells Certbot to use DNS validation instead of HTTP validation. DNS validation involves creating a TXT record for the domain name, which Certbot will use to verify ownership of the domain.

Example of obtaining a wildcard domain DNS TLS certificate from Let’s Encrypt using Cloudflare as the DNS provider

If you don’t have an API key, you can generate one by going to your Cloudflare dashboard, clicking on your profile picture in the top right corner, selecting “My Profile”, and then scrolling down to the “API Tokens” section.

Generate the Wildcard Domain DNS TLS Certificate

Use the following command to obtain the wildcard domain DNS TLS certificate:

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /path/to/cloudflare.ini \
  -d '*.example.com' \
  -d example.com \
  --preferred-challenges dns-01

Make sure to replace /path/to/cloudflare.ini with the path to your Cloudflare API key credentials file. The credentials file should have the following format:

dns_cloudflare_email = your_email@example.com
dns_cloudflare_api_key = your_cloudflare_api_key

Replace your_email@example.com with your Cloudflare email address, and your_cloudflare_api_key with your Cloudflare API key.

Or use API token as recommended, as an example of cloudflare.ini:

# Cloudflare API token used by Certbot
dns_cloudflare_api_token = ...

Step 3: Install the Wildcard Domain DNS TLS Certificate

After running the above command, Certbot will generate the wildcard domain DNS TLS certificate and store it in a directory on your system. You can find the location of the certificate by running the following command:

sudo certbot certificates

This command will show a list of all the certificates installed on your system, including the wildcard certificate we just generated.

To use the certificate in your web server, you’ll need to configure the web server to use the certificate. The specific instructions for doing this will depend on the web server you’re using. Refer to the documentation for your web server for more information.

Congratulations! You now have a wildcard domain DNS TLS certificate from Let’s Encrypt.

Troubleshooting

certbot: error: unrecognized arguments: –dns-cloudflare-credentials cloudflare.ini

The dns_cloudflare plugin automates the process of completing a dns-01 challenge (DNS01) by creating, and subsequently removing, TXT records using the Cloudflare API. The plugin is not installed by default. To install it:

pip3 install certbot-dns-cloudflare

Unsafe permissions on credentials configuration file

Configuration file permission may cause warning like following:

Unsafe permissions on credentials configuration file: cloudflare.ini

This will cause a failure:

Certbot failed to authenticate some domains (authenticator: dns-cloudflare). The Certificate Authority reported these problems: Domain: example.com Type: unauthorized Detail: Incorrect TXT record “a32ds…” found at _acme-challenge.example.com

Hint: The Certificate Authority failed to verify the DNS TXT records created by –dns-cloudflare. Ensure the above domains are hosted by this DNS provider, or try increasing –dns-cloudflare-propagation-seconds (currently 10 seconds).

To fix this issue, just change configuration file permission:

chmod 600 cloudflare.ini

Then re-run certbot command should solve the issue.

See also:

References