dehydrated/README.maintainer

==========================================
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  <hostname>;
    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/<domainname>/privkey.pem
Certificate: /etc/dehydrated/certs/<domainname>/cert.pem
Intermediate Chain: /etc/dehydrated/certs/<domainname>/chain.pem
Certificate + Intermediate: /etc/dehydrated/certs/<domainname>/fullchain.pem

where <domainname> 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/