HTTPS

• About
• Requirements
• How It Works
• Configuration
• Remarks

---

About

Dealing with setup and renewal of SSL/TLS certificates can be a real burden sometimes. Therefore thingOS comes with an integrated mechanism that registers, generates and automatically updates the SSL/TLS certificates provided by the free Let's Encrypt service.

Requirements

Before proceeding, make sure you have:

• A public IP address that can be used to reach the (normally HTTPS) server that runs on your system; ports 443 and 80 must particularly be accessible on/forwarded to your thingOS setup.
• A fully qualified domain name that points to your public IP address; virtual hosts that act as reverse proxies on port 443 and 80 should also be fine. If dealing with dynamic public addresses, you may want to configure a Dynamic DNS service first.
• An email address that you can supply when registering your domain with Let's Encrypt.
• An HTTPS-capable server that runs on your setup and is capable of using the generated SSL certificate and key.

How It Works

Let's Encrypt service offers an API called ACME, allowing registration, certificate creation and renewal and more. The dehydrated project relies on this API to provide a convenient shell script to maange these certificates.

thingOS comes with a wrapper to this dehydrated script, present at /usr/sbin/dehydrated-wrapper. The wrapper will check whether SSL is configured for this system and will make sure the required directories are created. You can run the wrapper just like you would run dehydrated, from command line, if you need it. See dehydrated usage for a full command line reference.

Once configured, cron will check every 30 days to see if the certificate is about to expire and needs to be renewed. It does this by running dehydrated-wrapper -c. All output goes to /var/log/messages, marked with dehydrated tag. If certificate requires renewal, the /usr/libexec/dehydrated-hook script will be called with first argument set to deploy_challenge.

Let's Encrypt requires the server to correctly respond to a so-called HTTP-01 challenge to verify that the host is actually associated to the claimed domain. This validation requires the system to (temporarily) be able to serve a file containing a nonce at a well-known location, on port 80. To this end, thingOS includes a dump HTTP server built using socat, present at /usr/libexec/dehydrated-dumb-httpd. The dumb server is started by the /usr/libexec/dehydrated-hook call and automatically exists after 10 seconds.

When the certificate has been renewed, the /usr/libexec/dehydrated-hook will be called with first argument set to deploy_cert. It will make sure the new certificate file and private key files are placed in /data/etc/ssl and will reboot the system.

The HTTPS server that runs on the system reads the certificate files from /data/etc/ssl and uses them to create its required SSL context.

Configuration

1. Make sure you enable the dehydrated and socat packages, before building your OS. This should, in turn, enable the openssl (+ binary) package.

2. Make sure port 80 is free, by stopping any server that may listen on it.

3. Create the /data/etc/ssl directory, where you should place the following two text files:

   • /data/etc/ssl/domain, containing your FQDN
   • /data/etc/ssl/email, containing your email address

4. Register your domain with Let's Encrypt (make sure to read the terms first):

    dehydrated-wrapper --register --accept-terms
   

   You should now have a folder called /var/lib/dehydrated/accounts/.

5. Obtain the certificates for the first time:

    dehydrated-wrapper -c
   

   You should now have the certificate files as follows:

   • /data/etc/ssl/cert.pem
   • /data/etc/ssl/privkey.pem

6. Configure your HTTPS server to use the certificates. For Nginx, this would mean adding the following directives to the configuration:

    listen 443 ssl;
    ssl_certificate /data/etc/ssl/cert.pem;
    ssl_certificate_key /data/etc/ssl/privkey.pem;
   

Remarks

Here are a few remarks:

• thingOS does not automatically enable or run HTTPS servers such as Nginx, Apache or Lighttpd. It's up to you to configure your OS so that it includes and runs the HTTPS server that uses the generated certificate.

• HTTPS is the most common SSL/TLS service but the generated certificates can be just as well used for any other use cases where domain validation is required. From Let's Encrypt's FAQ: "Let's Encrypt certificates are standard Domain Validation certificates, so you can use them for any server that uses a domain name, like web servers, mail servers, FTP servers, and many more".

• Make sure your system does not run any service that listens on port 80; port 80 is temporarily used while obtaining the certificate to validate the HTTP-01 challenge. If you must run your service on port 80, you could tweak the /usr/libexec/dehydrated-hook to inform your service to serve the HTTP-01 challenge instead of starting the nc-based dumb HTTP server.

• If you want to start over with dehydrated, you can simply do a:

   rm -r /var/lib/dehydrated