Document safe and simple usage by services without root privileges (#7821)

Certificates are public information by design: they are provided by
web servers without any prior authentication required.  In a public
key cryptographic system, only the private key is secret information.

The private key file is already created as accessible only to the root
user with mode 0600, and these file permissions are set before any key
content is written to the file.  There is no window within which an
attacker with access to the containing directory would be able to read
the private key content.

Older versions of Certbot (prior to 0.29.0) would create private key
files with mode 0644 and rely solely on the containing directory
permissions to restrict access.  We therefore cannot (yet) set the
relevant default directory permissions to 0755, since it is possible
that a user could install Certbot, obtain a certificate, then
downgrade to a pre-0.29.0 version of Certbot, then obtain another
certificate.  This chain of events would leave the second
certificate's private key file exposed.

As a compromise solution, document the fact that it is safe for the
common case of non-downgrading users to change the permissions of
/etc/letsencrypt/{live,archive} to 0755, and explain how to use chgrp
and chmod to make the private key file readable by a non-root service
user.

This provides guidance on the simplest way to solve the common problem
of making keys and certificates usable by services that run without
root privileges, with no requirement to create a custom (and hence
error-prone) executable hook.

Remove the existing custom executable hook example, so that the
documentation contains only the simplest and safest way to solve this
very common problem.

Signed-off-by: Michael Brown <mbrown@fensystems.co.uk>

1 files changed, 11 insertions, 37 deletions

diff --git a/certbot/docs/using.rst b/certbot/docs/using.rst
index 27ae826bd..8ec172c24 100644
--- a/certbot/docs/using.rst
+++ b/certbot/docs/using.rst
@@ -485,43 +485,6 @@ If you want your hook to run only after a successful renewal, use
 
 ``certbot renew --deploy-hook /path/to/deploy-hook-script``
 
-For example, if you have a daemon that does not read its certificates as the
-root user, a deploy hook like this can copy them to the correct location and
-apply appropriate file permissions.
-
-/path/to/deploy-hook-script
-
-.. code-block:: none
-
-   #!/bin/sh
-
-   set -e
-
-   for domain in $RENEWED_DOMAINS; do
-           case $domain in
-           example.com)
-                   daemon_cert_root=/etc/some-daemon/certs
-
-                   # Make sure the certificate and private key files are
-                   # never world readable, even just for an instant while
-                   # we're copying them into daemon_cert_root.
-                   umask 077
-
-                   cp "$RENEWED_LINEAGE/fullchain.pem" "$daemon_cert_root/$domain.cert"
-                   cp "$RENEWED_LINEAGE/privkey.pem" "$daemon_cert_root/$domain.key"
-
-                   # Apply the proper file ownership and permissions for
-                   # the daemon to read its certificate and key.
-                   chown some-daemon "$daemon_cert_root/$domain.cert" \
-                           "$daemon_cert_root/$domain.key"
-                   chmod 400 "$daemon_cert_root/$domain.cert" \
-                           "$daemon_cert_root/$domain.key"
-
-                   service some-daemon restart >/dev/null
-                   ;;
-           esac
-   done
-
 You can also specify hooks by placing files in subdirectories of Certbot's
 configuration directory. Assuming your configuration directory is
 ``/etc/letsencrypt``, any executable files found in
@@ -686,6 +649,17 @@ your (web) server configuration directly to those files (or create
 symlinks). During the renewal_, ``/etc/letsencrypt/live`` is updated
 with the latest necessary files.
 
+For historical reasons, the containing directories are created with
+permissions of ``0700`` meaning that certificates are accessible only
+to servers that run as the root user.  **If you will never downgrade
+to an older version of Certbot**, then you can safely fix this using
+``chmod 0755 /etc/letsencrypt/{live,archive}``.
+
+For servers that drop root privileges before attempting to read the
+private key file, you will also need to use ``chgrp`` and ``chmod
+0640`` to allow the server to read
+``/etc/letsencrypt/live/$domain/privkey.pem``.
+
 .. note:: ``/etc/letsencrypt/archive`` and ``/etc/letsencrypt/keys``
    contain all previous keys and certificates, while
    ``/etc/letsencrypt/live`` symlinks to the latest versions.