HOWTO: Use certbot with Let’s Encrypt wildcard certificates

Let's Encrypt Logo White Background

Let’s Encrypt has just added support for wildcard certificates to its ACMEv2 production servers.

I couldn’t find a simple guide on how to use it to create wildcard certificates for my domains, but I figured it out, so here’s how I did it.

Use Certbot From Github

The packaged version of certbot doesn’t support wildcare domains yet, so we’ll need to install certbot from the github repo:

$ git clone https://github.com/certbot/certbot
$ cd certbot
$ sudo python setup.py install

Configure a DNS Authenticator

Using wildcard certificates requires you to use DNS based authentication, which adds a custom TXT record to the DNS for the base domain you’re using to verify that you are in control of the domain you’re getting a certificate for.

You will need a DNS authenticator plugin for certbot. Several are available, but I’m going to use CloudFlare for this example.

Check to see which plugins are available for your certbot environment as follows.

$ certbot plugins
-------------------------------------------------------------------------------
* nginx
Description: Nginx Web Server plugin - Alpha
Interfaces: IAuthenticator, IInstaller, IPlugin
Entry point: nginx = certbot_nginx.configurator:NginxConfigurator

* standalone
Description: Spin up a temporary webserver
Interfaces: IAuthenticator, IPlugin
Entry point: standalone = certbot.plugins.standalone:Authenticator

* webroot
Description: Place files in webroot directory
Interfaces: IAuthenticator, IPlugin
Entry point: webroot = certbot.plugins.webroot:Authenticator
-------------------------------------------------------------------------------

The plugin isn’t installed yet, so we need to add it.

Adding the CloudFlare DNS Authenticator Plugin

$ cd certbot-dns-cloudflare
$ sudo python setup.py install

Now we see the plugin is available for use:

$ certbot plugins
-------------------------------------------------------------------------------
* dns-cloudflare
Description: Obtain certificates using a DNS TXT record (if you are using
Cloudflare for DNS).
Interfaces: IAuthenticator, IPlugin
Entry point: dns-cloudflare =
certbot_dns_cloudflare.dns_cloudflare:Authenticator

* nginx
Description: Nginx Web Server plugin - Alpha
Interfaces: IAuthenticator, IInstaller, IPlugin
Entry point: nginx = certbot_nginx.configurator:NginxConfigurator

* standalone
Description: Spin up a temporary webserver
Interfaces: IAuthenticator, IPlugin
Entry point: standalone = certbot.plugins.standalone:Authenticator

* webroot
Description: Place files in webroot directory
Interfaces: IAuthenticator, IPlugin
Entry point: webroot = certbot.plugins.webroot:Authenticator
-------------------------------------------------------------------------------

 

Adding the Plugin With Pip

Alternately, you can install the plugin from published packages using pip.

$ sudo pip3 install certbot-dns-cloudflare

Configuring Plugin API Credentials

To use the authenticator plugin with CloudFlare, you need to be able to authenticate to CloudFlare so it will let you edit the domain entries to add your TXT entry to verify you control the domain.

Because Let’s Encrypt means we can do automated certificate renewals, we have to let the computer make DNS edits automatically. This is slightly problematic, because it means you can’t use 2-factor authentication on this mechanism (or you’d have to wake up in the middle of the night to insert your Yubikey in a server in a datacentre on the other side of the world… somehow). You’ll need to obtain API credentials for your DNS provider, and then ensure these are kept very safe on the server doing the automated certificate renewals.

CloudFlare, for example, doesn’t let you lock down what the API access can be used for, or where the requests can come from. It’s an all-or-nothing proposition, which is not ideal, so be aware of the risks before you set this up.

You obtain the Global API key in CloudFlare from your user profile. It looks like this:

Getting API keys from CloudFlare

Getting API keys from CloudFlare

Put these keys into a configuration file. certbot uses a default directory of /etc/letsencrypt, so let’s create a file called /etc/letsencrypt/dnscloudflare.ini to store these credentials. The format of the file is like this:

# CloudFlare API key information
dns_cloudflare_api_key = blahblahblah44399342234bland
dns_cloudflare_email = [email protected]

Make sure the file is not world readable.

$ chmod 600 /etc/letsencrypt/dnscloudflare.ini

Certbot Configuration Settings

Wildcard certificates are only available via the v2 API, which isn’t baked into certbot yet, so we need to explicitly tell certbot where to find it using the server parameter. For this example, I’ll be using the staging API endpoint which is designed for testing. Change it to the production API when you’re satisfied everything else is set up correctly.

Certbot uses the /etc/letsencrypt/cli.ini configuration file:

# Let's Encrypt site-wide configuration
dns-cloudflare-credentials = /etc/letsencrypt/dnscloudflare.ini
# Use the ACME v2 staging URI for testing things
server = https://acme-staging-v02.api.letsencrypt.org/directory
# Production ACME v2 API endpoint
#server = https://acme-v02.api.letsencrypt.org/directory

Get a Wildcard Certificate

If we’ve configured everything correctly, certbot should now be able to automatically request a new wildcard certificate via the ACME v2 API and use the CloudFlare API to put the required TXT entry in the domain’s DNS records via the dns-cloudflare authentication plugin.

$ sudo certbot certonly -d *.eigenmagic.com --dns-cloudflare

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Plugins selected: Authenticator dns-cloudflare, Installer None
Starting new HTTPS connection (1): acme-staging-v02.api.letsencrypt.org
Obtaining a new certificate
Performing the following challenges:
dns-01 challenge for eigenmagic.com
Starting new HTTPS connection (1): api.cloudflare.com
Waiting 10 seconds for DNS changes to propagate
Waiting for verification...
Cleaning up challenges
Starting new HTTPS connection (1): api.cloudflare.com

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
 /etc/letsencrypt/live/eigenmagic.com/fullchain.pem
 Your key file has been saved at:
 /etc/letsencrypt/live/eigenmagic.com/privkey.pem
 Your cert will expire on 2018-06-12. To obtain a new or tweaked
 version of this certificate in the future, simply run certbot
 again. To non-interactively renew *all* of your certificates, run
 "certbot renew"
 - If you like Certbot, please consider supporting our work by:

Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate
 Donating to EFF: https://eff.org/donate-le

Now you can use wildcard certificates with your usual certificate installation method.

Enjoy!

Bookmark the permalink.

10 Comments

  1. Thanks mate, helped a lot!

  2. Hey,

    first of all, thanks.

    I can setup TXT DSN Records on my own, why do i need an external DNS provider?

  3. You only need one if you want to use one of the plugins that come with certbot to do the authorisation step in a fully automated way. It’s quite handy for certificate renewals, since Let’s Encrypt certificates expire after three months. Automating the renewal on a schedule via something like cron is useful, lest you forget to renew your cert and then your TLS is broken until you remember to renew the cert using the manual approach.

    But if you’re happy with a slightly more manual approach, go for it!

  4. Hi Justin: I’m following your article to a T, however I got halted by this baffling error when I try to run
    “Wildcard certificates are only available via the v2 API, which isn’t baked into certbot yet, so we need to explicitly tell certbot where to find it using the
    server
    parameter”

    the error:
    ~$ server
    WARNING: Usage of “server” is deprecated, it has been renamed to “rspserver”!
    Starting service Echo…
    Echo Server – Version 1.0
    =========================

    General Parameters:
    Pool Handle = EchoPool
    Reregistration Interval = 30.000s
    Local Addresses = { all }
    Runtime Limit = off
    Policy Settings
    Policy Type = RoundRobin
    Load Degradation = 0.000%
    Load DPF = 0.000%
    Weight = 0
    Weight DPF = 0.000%
    24-Mar-2018 12:27:17.0214: [email protected] rserpoolsocket.c:354 doRegistration()
    24-Mar-2018 12:27:17.0215: Error: (Re-)Registration failed: no registrar available
    How do I correct this error to finalize the wild certificate emission?
    Thank you

  5. Environment: Ubuntu 16.04 with certbot 0.22
    Following your article, got an error at this step:
    “Certbot Configuration Settings
    Wildcard certificates are only available via the v2 API, which isn’t baked into certbot yet, so we need to explicitly tell certbot where to find it using the
    server
    parameter”

    The error:
    ~$ server
    WARNING: Usage of “server” is deprecated, it has been renamed to “rspserver”!
    Starting service Echo…
    Echo Server – Version 1.0
    =========================

    General Parameters:
    Pool Handle = EchoPool
    Reregistration Interval = 30.000s
    Local Addresses = { all }
    Runtime Limit = off
    Policy Settings
    Policy Type = RoundRobin
    Load Degradation = 0.000%
    Load DPF = 0.000%
    Weight = 0
    Weight DPF = 0.000%
    24-Mar-2018 12:55:11.8902: [email protected] rserpoolsocket.c:354 doRegistration()
    24-Mar-2018 12:55:11.8903: Error: (Re-)Registration failed: no registrar available
    What corrections actions do I need to do execute fix this error?
    Thank you

  6. Never mind, I figure it out
    Thank you

  7. Thanks for the laser clear instructions!

    For anyone else who, following successful wildcard cert creation, does a dry run to test renewal:

    `certbot renew –dry-run`

    and gets back:

    `–server value conflicts with –dry-run`

    Open cli.ini, comment out production server, uncomment staging, and do the dry run again.

    Upon successful dry run renewal, remember to open cli.ini and switch back to production.

    Please correct me if this goes against best practice.

  8. Great instructions.
    Q. As this is a wildcard, im a possible use could be to use the same SSL on various different servers. Say you had webmail, adfs, web, BYOD etc all to secure with this one SSL, then how would you go about replacing them all after 3 months?

    I take it there is no automation apart from the renew on the one server running certbot?

    Thanks

  9. Correct, this is just the part that renews the wildcard certificate that you can then use in multiple places.

    You could just have a separate cert for each of those places that autorenews itself, but sometimes you have other devices that can’t (or you don’t want them to) talk to the Internet. This process just grabs the certificate, and you’d then need another process that takes the new cert and installs it onto all those other devices.

    How that process works is highly dependent on the devices and how they work, so it’d need to be tailored to your specific needs.

  10. Hamid Pourgholi

    For me (Ubuntu 16.04 server) it was also required to install python-setuptools. Without that i got an exceptions in the step: sudo python setup.py install

    I had to run:

    sudo apt-get install python-setuptools

Comments are closed