forked from pool/dehydrated
af93c182f3
OBS-URL: https://build.opensuse.org/package/show/security:dehydrated/dehydrated?expand=0&rev=75
245 lines
8.6 KiB
Plaintext
245 lines
8.6 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
|
|
=====================
|
|
|
|
* 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/
|