Wildcard Let’s Encrypt certificate with DNS validation

SSL 3 min read

A wildcard certificate (*.pelda.hu) protects all top-level subdomains of the domain, so there is no need to apply for a separate certificate for each new subdomain. Let’s Encrypt issues wildcard certificates free of charge, but only with DNS validation: ownership of the domain must be verified using a TXT record named _acme-challenge.pelda.hu.

This is not usually necessary for cPanel hosting plans, as AutoSSL automatically requests a certificate for every subdomain. This article is intended for those operating their own VPS or dedicated server.

What should you look out for?

  • *.pelda.hu only protects the subdomains, not the pelda.hu address itself. Therefore, please request both: -d pelda.hu -d '*.pelda.hu'.
  • A wildcard only covers one level: it applies to the address bolt.pelda.hu, but not to teszt.bolt.pelda.hu.
  • The TXT record must be recreated at every renewal. As manual creation means renewal cannot be automated, please use a tool that creates the record automatically via the DNS provider’s API.

acme.sh is a lightweight ACME client that supports the APIs of over a hundred DNS providers.

Installation

curl https://get.acme.sh | sh -s email=it@pelda.hu
source ~/.bashrc
acme.sh --set-default-ca --server letsencrypt

The last command sets Let’s Encrypt as the default certificate authority, as acme.sh uses ZeroSSL by default.

Request this if your DNS is hosted with Cloudflare

Create an API token in Cloudflare with ‘Zone → DNS → Edit’ permissions for the relevant domain, then:

export CF_Token="a-cloudflare-api-token"
acme.sh --issue --dns dns_cf -d pelda.hu -d '*.pelda.hu'

Request this if your DNS is hosted on your cPanel hosting account

If your domain uses our name servers and you manage the DNS zone via cPanel, acme.sh can also create the record via the cPanel API. Create an API token in cPanel (Security → Manage API Tokens), then:

export cPanel_Username="cpanel-felhasznalonev"
export cPanel_Apitoken="a-cpanel-api-token"
export cPanel_Hostname="https://a-cpanel-szerver-neve:2083"
acme.sh --issue --dns dns_cpanel -d pelda.hu -d '*.pelda.hu'

The API token grants full access to your cPanel account, so please treat it as you would a password.

Installation on the web server

acme.sh --install-cert -d pelda.hu \
  --key-file       /etc/ssl/pelda.hu.key \
  --fullchain-file /etc/ssl/pelda.hu-fullchain.crt \
  --reloadcmd      "systemctl reload nginx"

During installation, acme.sh also sets up a daily cron job which renews the certificate on time, copies it to the locations listed above, and restarts the web server. It saves the API details, so there is no need to re-enter them for renewal.

With Certbot

Certbot can also request a wildcard certificate if it has an extension for your DNS provider. For example, in the case of Cloudflare:

dnf install python3-certbot-dns-cloudflare   # vagy: apt install python3-certbot-dns-cloudflare

cat > /root/.cloudflare.ini <<'EOF'
dns_cloudflare_api_token = a-cloudflare-api-token
EOF
chmod 600 /root/.cloudflare.ini

certbot certonly --dns-cloudflare \
  --dns-cloudflare-credentials /root/.cloudflare.ini \
  -d pelda.hu -d '*.pelda.hu'

Renewal is automatic, just as it is for other Certbot certificates; see: Applying for a Let’s Encrypt certificate with Certbot.

Manual DNS validation (for one-off use only)

If your DNS provider does not offer an API, you can create the record manually:

certbot certonly --manual --preferred-challenges dns -d pelda.hu -d '*.pelda.hu'

Certbot displays the name and value of the TXT record to be created. Create it in the DNS, wait until it becomes visible (run dig TXT _acme-challenge.pelda.hu +short), and only then press Enter. The certificate obtained in this way does not renew automatically; you must repeat the process before it expires. It is therefore not recommended as a long-term solution.

Tip: CNAME delegation

If you do not wish to store the API key granting access to the entire DNS zone on the server, you can redirect the name _acme-challenge.pelda.hu, using a CNAME record, to another zone used solely for this purpose, to which you have API access. acme.sh supports this via the --challenge-alias switch.

If there is a CAA record on the domain, it should include letsencrypt.org; for a wildcard certificate, it should also include the issuewild tag, if you are using such a record.

Back: SSL articles (35)