Using Let’s Encrypt SSL Certificates

Table of Contents

Introduction
Requirements & Dependencies
Install Let’s Encrypt’s Certbot Client
Updating Certbot
Register Your Email Address
Create Let’s Encrypt’s Config Files
Create an SSL Certificate
Listing Existing Certificates
Web Server Setup
Test the Setup
Renewing SSL Certificates
Add Extra Domains to the Certificate
Deleting SSL Certificates

Introduction

This page covers how to configure your web server to use Let’s Encrypt as the certificate authority for your ownCloud server. Note that Let’s Encrypt is not officially supported, and this page is community-maintained.

For ease of handling, SSL-specific directives have been moved into a separate file to be included. This can help with first-time certificate issuance as well as with reusing configurations.
Read the Certbot user guide for details of the commands.
Let’s Encrypt CA issues short-lived certificates valid for 90 days. Make sure you renew the certificates at least once in this period, because expired certificates need reissuing. A certificate is due for renewal at the earliest 30 days before expiring. Certbot can be forced to renew via options at any time as long as the certificate is valid.

Raymii.org provides raymii-ssl-url[an excellent introduction to strong SSL security measures with Apache], if you would like to know more.

Requirements & Dependencies

You require a domain name with a valid A-Record pointing back to your server’s IP address. In case your server is behind a firewall, ensure that your server is accessible from the internet by adding the required firewall and port forwarding rules.

Install Let’s Encrypt’s Certbot Client

certbot has updated the prerequisites and the way to install the certbot script. You can find how to install it on certbot instructions. Follow one of the possible ways and continue when ready.

If you have used certbot-auto before, read how to upgrade in the certbot-auto section.

In general, to run Certbot, use the following command:

sudo certbot

Updating Certbot

Because certbot is using snap for Ubuntu, there is no need to manually check for updates. Snap checks this automatically and does not require admin intervention, although you can configure the update behavior. For details see the Snap getting started documentation.

Register Your Email Address

First Time Registration

Now that Certbot is installed, register your email address for urgent renewal and security notifications. This command also prepares Certbot’s environment if it’s not already installed. To do this, run the following command:

sudo certbot register --agree-tos --email <your-email-address>

When it executes, you’ll see a question similar to the following, which you can answer "Yes" or "No":

Saving debug log to /var/log/letsencrypt/letsencrypt.log

-------------------------------------------------------------------------------
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about EFF and
our work to encrypt the web, protect its users and defend digital rights.
-------------------------------------------------------------------------------
(Y)es/(N)o:

When that completes, you’ll see a message similar to the following:

IMPORTANT NOTES:
 1. Your account credentials have been saved in your Certbot
    configuration directory at /etc/letsencrypt. You should make a
    secure backup of this folder now. This configuration directory will
    also contain certificates and private keys obtained by Certbot so
    making regular backups of this folder is ideal.

Please, strongly, consider following its recommendation.

Update Your Registration

In case you want to update your registered email address use following command:

This will affect all the certificates issued using this account.

sudo certbot register --update-registration --email <your-email-address>

When that completes, you’ll see a message similar to the following:

Saving debug log to /var/log/letsencrypt/letsencrypt.log

-------------------------------------------------------------------------------
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about EFF and
our work to encrypt the web, protect its users and defend digital rights.
-------------------------------------------------------------------------------
(Y)es/(N)o: y

IMPORTANT NOTES:
 - Your e-mail address was updated to <your-email-address>

Create Let’s Encrypt’s Config Files

Because remembering all the possible options for certbot is difficult, the following scripts ease the use for common tasks because of their self-descriptive name.

Create the following files in the Let’s Encrypt directory which can usually be found in /etc/letsencrypt. Rename <your-domain-name>.sh with the name of the domain(s) you want to issue a certificate for.
```
cd /etc/letsencrypt
sudo touch cli.ini list.sh renew.sh renew-cron.sh delete.sh <your-domain-name>.sh
```
Make all files created executable except cli.ini by running
```
sudo chmod +x *.sh
```

Use sudo when running the scripts (unless you are already logged in as the root user)

All scripts have to be executed with sudo as certbot requires enhanced privileges.

If you’re logged in to your server as a user other than root, you’ll likely need to put sudo before your Certbot commands so that they run as root (for example, sudo certbot instead of just certbot)

cli.ini

This file defines some default settings used by Certbot. Use the email address you registered with. Comment or uncomment the post-hook parameter depending on if you want to run post hooks. Running post hooks will reload the web server configuration automatically if a certificate has been renewed.

rsa-key-size = 4096
email = <your-email-address>
agree-tos = True
authenticator = webroot
# post-hook = service apache2 reload

For the following scripts, replace the path to Certbot and the Certbot script name based on your installation. You can find it by running:

which certbot

list.sh

This script lists all your issued certificates.

#!/bin/bash

LE_PATH="/usr/bin"
LE_CB="certbot"

"$LE_PATH/$LE_CB" certificates

renew.sh

This script:

Renews all your issued certificates.
In case you have enabled the post hook for your web server in cli.ini, it will reload the web server configuration automatically if a certificate has been renewed.

#!/bin/bash

LE_PATH="/usr/bin"
LE_CB="certbot"

"$LE_PATH/$LE_CB" renew

renew-cron.sh

This script:

Renews all your issued certificates but does not upgrade Certbot.
In case you have enabled the post hook for your web server in cli.ini, it will reload the web server configuration automatically if a certificate has been renewed.

This script is intended for use via Cron.

#!/bin/bash

LE_PATH="/usr/bin"
LE_CB="certbot"

"$LE_PATH/$LE_CB" renew --no-self-upgrade --noninteractive

delete.sh

This script deletes an issued certificate.
Use the list.sh script to list issued certificates.

#!/bin/bash

LE_PATH="/usr/bin"
LE_CB="certbot"

##
## Retrieve and print a list of the installed Let's Encrypt SSL certificates.
##
function get_certificate_names()
{
  "$LE_PATH/$LE_CB" certificates | grep -iE "certificate name" | awk -F: '{gsub(/\s+/, "", $2); printf("- %s\n", $2)}'
}

echo "Available Certificates:"

get_certificate_names
echo

read -p "Which certificate do you want to delete: " -r -e answer
if [ -n "$answer" ]; then
  "$LE_PATH/$LE_CB" delete --cert-name "$answer"
fi

<your-domain-name>.sh

The following example script creates a certificate for a domain or sub-domains, which can be added or removed as necessary. Replace (sub-domain.)example.com with your domain or sub-domain names. The first (sub)domain name in the script is used for naming the directories created by Certbot.

You can create different certificates for different sub-domains, such as example.com, www.example.com, and subdomain.example.com by creating different scripts.

#!/bin/bash
# export makes the variable available for all subprocesses

LE_PATH="/usr/bin"
LE_CB="certbot"

# Assumes that example.com www.example.com and subdomain.example.com are the domains
# that you want a certificate for
export DOMAINS="-d example.com -d www.example.com -d subdomain.example.com"

"$LE_PATH/$LE_CB" certonly --config /etc/letsencrypt/cli.ini "$DOMAINS" # --dry-run

You can enable the --dry-run option which does a test run of the client only.

Create an SSL Certificate

With all the scripts created, to create an SSL certificate, run the following command:

sudo /etc/letsencrypt/<your-domain-name>.sh

After you run the script, you will see output similar to the following:

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Obtaining a new certificate
Performing the following challenges:
http-01 challenge for your-domain-name.com
Using the webroot path /var/www/html for all unmatched domains.
Waiting for verification...
Cleaning up challenges
Running post-hook command: service apache2 reload

IMPORTANT NOTES:
 1. Congratulations! Your certificate and chain have been saved at:
    /etc/letsencrypt/live/your-domain-name.com/fullchain.pem
    Your key file has been saved at:
    /etc/letsencrypt/live/your-domain-name.com/privkey.pem
    Your cert will expire on 2018-06-18. 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"
 2. 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

You can see that the SSL certificate has been successfully created and that it will expire on 2018-06-18.

Listing Existing Certificates

If you want to list (view) existing SSL certificates, use list.sh, which can be run as follows:

sudo /etc/letsencrypt/list.sh

Depending on the number of certificates, you can expect to see output similar to the following:

-------------------------------------------------------------------------------
Found the following certs:
  Certificate Name: your-domain-name.com
    Domains: your-domain-name.com
    Expiry Date: 2018-06-18 10:57:18+00:00 (VALID: 82 days)
    Certificate Path: /etc/letsencrypt/live/your-domain-name.com/fullchain.pem
    Private Key Path: /etc/letsencrypt/live/your-domain-name.com/privkey.pem
-------------------------------------------------------------------------------

Web Server Setup

Refer to the Apache setup guide, to set up your web server and issue a certificate.

Test the Setup

After you have setup and configured the web server and installed the SSL certificate using Certbot, you should now test the security of your new configuration. To do so, you can use the free service of SSL Labs. See an example screenshot of a test run below.

ssllabs

Renewing SSL Certificates

As Let’s Encrypt certificates expire every 90 days, ensure you renew them before that time.
There are two ways to do so: manually and automatically.

Manual Renewal

If you have provided your email address, you will receive reminder notifications.

sudo /etc/letsencrypt/renew.sh

If the certificate is not yet due for renewal, you can expect to see output similar to that below:

-------------------------------------------------------------------------------
Processing /etc/letsencrypt/renewal/your-domain-name.com.conf
-------------------------------------------------------------------------------
Cert not yet due for renewal

The following certs are not due for renewal yet:
  /etc/letsencrypt/live/your-domain-name.com/fullchain.pem (skipped)
No renewals were attempted.
No hooks were run.

Automatic Renewal via Crontab

Certificates are only renewed if they are due, so you can schedule Cron jobs to renew your SSL certificates on a more frequent basis. However, a weekly check is sufficient.

To add a new Cron job to auto-renew your certificates, firstly run the following command to edit the job list.

sudo crontab -e

It is essential to use sudo to derive proper permissions.

Then, add the following at the end of the existing configuration:

30 03 * * 6 /etc/letsencrypt/renew-cron.sh

After you save and exit the file, the new job will have been added to the Cron job scheduler.

If you want to use different values, you can check them e.g. at crontab.guru and modify the script with your preferred options.

Add Extra Domains to the Certificate

If you want to add an extra domain, like subdomain.example.com, to your certificate, add the domain in the domain shell script above, re-run it and reload the web server config. This can be useful when migrating from a sub-directory for your ownCloud instance to sub-domain access.

This means you need to comment the include directive (see the relevant web server setup) and follow the steps afterwards.

Deleting SSL Certificates

If you want to delete an SSL certificate, use the delete.sh script, running it as follows:

sudo /etc/letsencrypt/delete.sh

It will start off by displaying a list of the currently available SSL certificate domain names, as in the example below, and then prompt you to supply the certificate you want to delete.

Available Certificates:

1. your-domain-name.com

Which certificate do you want to delete:

Provide the SSL certificate name that you want to delete and click enter, and the certificate and all of its related files will be deleted. After that you should expect to see a confirmation, as in the example output below.

-------------------------------------------------------------------------------
Deleted all files relating to certificate your-domain-name.com.
-------------------------------------------------------------------------------