169bd5f56b
transition case in the maintainer README. Unlikely enough. The versions that have not transitioned yet would be broken for more than two years now. OBS-URL: https://build.opensuse.org/package/show/security:dehydrated/dehydrated?expand=0&rev=59
174 lines
6.2 KiB
Plaintext
174 lines
6.2 KiB
Plaintext
==========================================
|
|
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
|
|
=====================
|
|
|
|
* It is currently not possible to aqcuire Wildcard certificates
|
|
* 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
|
|
=============
|
|
|
|
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/
|