========================================== Acquiring TLS Certificates with Dehydrated ========================================== The dehydrated package has been designed to make acquiring TLS certificates (aka SSL Certificates) as simple as possible, while still being useful in a broad amount of use cases. Please consult the dehydrated man page, then continue reading here. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! IMPORTANT: On systemd-based systems, you need to enable the update timer, which has obsoleted the cron job. This is independent on which method you chose from below! # systemctl enable dehydrated.timer Also note that with the systemd timer, failures will not be mailed to the system administrator, but are being logged to the systemd journal, as per systemd's design philosophy. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Acquisition through HTTP (http-01) =================================== This is the primary method of acquiring certifictes. The Certificate Authority will provide a challenge that the requestor needs to provide via HTTP on port 80/TCP, in /.well-known/acme-challenge/. Setting up the acme-challenge auto-responder -------------------------------------------- Apache (easiest) ~~~~~~~~~~~~~~~~ If you are using Apache, just install dehydrated-apache2 and reload Apache. This will take care of setting up the acme-challenge auto-responder. nginx ~~~~~ (not part of SLE, use openSUSE backports) For nginx, you will need to install dehydrated-nginx. Unfortunately, nginx does not support directory mappings across vhosts, so in addition you will need to include "/etc/nginx/acmechallenge" in all vhost configurations like this: server { listen 80; listen [::]:80; server_name ; include "acmechallenge"; location / { return 301 https://$host$request_uri; } } lighttpd ~~~~~~~~ (not part of SLE, use openSUSE backports) Lighttpd users can use the following snippet: server.modules += ("mod_alias") alias.url += ( "/.well-known/acme-challenge/" => "/var/lib/acme-challenge/", ) NOTE: Never set up the SSL vhosts until you have initially acquired the first host. Specifying an SSL vhost without certificates constitutes an error for web servers. NOTE: The dehydrated-lighttpd package has been removed. Please use the snippet above. Machines without a webserver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On machines that are not running any web server, e.g. mail relays, you can run apache2 with dehydrated-apache2. If you do not want to run any web server on a system with systemd permnently, you can use dehydrated-acmeresponder. This is a small socket activated server. Once installed, it will automatically listen on port 80 whenever the dehydrated cron job seeks renewal, assuming no other server is currently occupying the port. It will also shut down once the timer has finished execution. Acquisition of initial certificate ---------------------------------- How set up an account as described in the man page (as root): # dehydrated --register --accept-terms (the current version of the LetsEncrypt Terms & Conditions are referenced in /etc/dehydrated/config) Next, fill in domains.txt and acquire the initial certificates (again, as root): # echo "myhost.example.com myalias.example.com" >> domains.txt # dehydrated --cron adds myhost.example.com to the list of host names we want to request a certificate for. The certificate will hold a Subject Alternative Name of "myalias.example.com". LetsEncrypt will check both host names. NOTE: As of 2017, LetsEncrypt certificates are only valid for three months, and the validity period may be further reduced in the future. It is therefore vital to ensure that the certificates are being automatically renewed. On systems without systemd, a cron job is automatically set up to take care of this. On systemd-enabled systems, a timer is provided which needs to be activated manually: # systemctl enable dehydrated.timer Aqcuisition through DNS (dns-01) ================================ This is mostly useful under these conditions 1. Your hosts are not directly exposed to the internet 2. Your host names are part of a public DNS zone visible on the internet. 3. You are comfortable with the service adding and removing records in your domain. Usually, the scenario you want this is a central host which picks up certificates for all other hosts on a network, and then deploys them to the actual target host, using plain scp or configuration management tools like Ansible or Salt. For details, please refer to dns-verification.md. For openSUSE, the python-dns-lexicon package provides hooks into many DNS providers and DNS servers. Proceeding after initial certificate aquisition =============================================== Setting up the SSL host ----------------------- As recommended parameters shift, please refer to Mozillas excellent SSL Configuration Generator [1] for details on how to configure your web server. Replace the example paths with the following: Key: /etc/dehydrated/certs//privkey.pem Certificate: /etc/dehydrated/certs//cert.pem Intermediate Chain: /etc/dehydrated/certs//chain.pem Certificate + Intermediate: /etc/dehydrated/certs//fullchain.pem where should be the name of the first column in domains.txt Limitations & Ceveats ===================== * No EV- or OV-validated certificates * Certificates expire within weeks, not years. This is by design. Ensure that certificate renewal works and that daemons get reloaded frequently to pick up certificate updates. Apache will work due to log rotation SIGHUP'ing the process frequently. However, any other actions, such as service reloads need to be provided as a script in /etc/dehydrated/postrun-hooks.d, which will be executed by the cron script / systemd timer *after* an update run has been performed. Upgrade Notes ============= v0.7.0 ------ Postrun Hooks ~~~~~~~~~~~~~ dehydrated.service no longer starts scripts in /etc/dehydrated/postrun-hooks.d/ directly, the support was moved to a separate unit file. Please run systemctl enable dehydrated-postrun-hooks.service to restore this functionality. This change was required to ensure that the output of the dehydrated script stays attached to the dehydrated unit in the journal. Key Algorithm ~~~~~~~~~~~~~ If you are upgrading from dehydrated <= 0.6.5, the new default for new installations changes from KEY_ALGO=rsa to KEY_ALGO=secp384r1 This switches the algorithm for newly issued certificates from RSA to the elliptic curve (EC) based secp384r1 algorithm. While both are considered sufficiently compatible to current software in public environments and SUSE supports EC even in SLES 12, some 3rd party software and/or appliances may still not yet be compatible with EC algorithms. In these environments, the KEY_ALGO setting needs to be set to "rsa" manually. If you are receiving errors about an invalid key length, comment out the KEYSIZE option. Extended use of the CA variable / New ACME providers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Starting with 0.7.0, dehydrated supports additional, commercial certificate providers that use the ACME protocol to automatically issue certificates. The CA config variable, which so far expected a URL to a ACME API endpoint can now contain the following shorthand service strings instead, which are internally converted to the API URLs and hence are equivalent: * LetsEncrypt: "letsencrypt" (staging environment: "letsencrypt-test") * BuyPass: "buypass" (test environment: "buypass-test") * ZeroSSL: "zerossl" LetsEncrypt remains the default provider. If you prefer to use the URL instead, you can continue to do so. Note: ZeroSSL requires additional the options EAB_KID and EAB_HMAC_KEY to be set. Please consult the ZeroSSL documentation fore more information. ACME v1 deprecation ~~~~~~~~~~~~~~~~~~~ The upstream project has deprecated ACME v1 in favor of the IETF- blessed [1] ACME v2 protocol. While dehydrated still supports v1-based verification flows, future versions might no longer do. If you are using a custom ACME endpoint URL, you can check compliance with the ACME v2 protocol by consulting your ACME service provider's documentation. Verify by setting API=2 in the config file and then running "dehydrated --cron". [1] https://tools.ietf.org/html/rfc8555 v0.3.1 ------ If you are upgrading from letsencrypt.sh, note that you need to move /etc/letsencrypt.sh to /etc/dehydrated and chown it to the "dehydrated" user. Links ===== [1] https://mozilla.github.io/server-side-tls/ssl-config-generator/