Merge tag 'v0.8.0' into debian/latest

Release version 0.8.0

1 files changed, 193 insertions, 85 deletions

diff --git a/lacme.8.md b/lacme.8.md
index 4098662..ad6dab6 100644
--- a/lacme.8.md
+++ b/lacme.8.md
@@ -37,9 +37,9 @@ with its own executable:
     For certificate issuances (`newOrder` command), it also generates
     Certificate Signing Requests, then verifies the validity of the
     issued certificate, and optionally reloads or restarts services when
-    the *notify* option is set.
+    the *notify* setting is set.
 
- 3. An actual [ACME] client (specified with the *command* option of the
+ 3. An actual [ACME] client (specified with the *command* setting of the
     [`[client]` section](#client-section) of the configuration file),
     which builds [ACME] commands and dialogues with the remote [ACME]
     server.
@@ -49,7 +49,7 @@ with its own executable:
     requested by writing the data to be signed to the socket.
 
  4. For certificate issuances (`newOrder` command), an optional
-    webserver (specified with the *command* option of the [`[webserver]`
+    webserver (specified with the *command* setting of the [`[webserver]`
     section](#webserver-section) of the configuration file), which is
     spawned by the “master” `lacme`.  (The only challenge type currently
     supported by `lacme` is `http-01`, which requires a webserver to
@@ -77,7 +77,7 @@ Commands
     Upon success, `lacme` prints the new or updated Account Object from
     the [ACME] server.
 
-`lacme` [`--config-certs=`*FILE*] [`--min-days=`*INT*] `newOrder` [*SECTION* …]
+`lacme newOrder` [`--config-certs=`*FILE*] [`--min-days=`*INT*|`--force`] [*SECTION* …]
 
 :   Read the certificate configuration *FILE* (see the **[certificate
     configuration file](#certificate-configuration-file)** section below
@@ -85,29 +85,38 @@ Commands
     for each of its sections (or the given list of *SECTION*s).
     Command alias: `new-order`.
 
+    The flag `--force` is an alias for `--min-days=-1`, which forces
+    renewal regardless of the expiration date of existing certificates.
+
 `lacme` `revokeCert` *FILE* [*FILE* …]
 
 :   Request that the given certificate(s) *FILE*(s) be revoked.  For
     this command, [`lacme-accountd`(1)] can be pointed to either the
-    account key or the server's private key.
+    account key or the certificate key.
     Command alias: `revoke-cert`.
 
-Generic options
-===============
+Generic settings
+================
 
 `--config=`*filename*
 
-:    Use *filename* as configuration file.  See the **[configuration
-     file](#configuration-file)** section below for the configuration
-     options.
+:   Use *filename* as configuration file instead of
+    `%E/lacme/lacme.conf`.  The value is subject to [%-specifier
+    expansion](#percent-specifiers).
+
+    See the **[configuration file](#configuration-file)** section below
+    for the configuration options.
 
 `--socket=`*path*
 
 :   Use *path* as the [`lacme-accountd`(1)] UNIX-domain socket to
-    connect to for signature requests from the [ACME] client.  `lacme`
-    aborts if `path` is readable or writable by other users, or if its
-    parent directory is writable by other users.
-    This command-line option overrides the *socket* option of the
+    connect to for signature requests from the [ACME] client.  The value
+    is subject to [%-specifier expansion](#percent-specifiers).
+    `lacme` aborts if *path* exists or if its parent directory is
+    writable by other users.
+    Default: `%t/S.lacme`.
+
+    This command-line option overrides the *socket* setting of the
     [`[client]` section](#client-section) of the configuration file; it
     also causes the [`[accountd]` section](#accountd-section) to be
     ignored.
@@ -127,12 +136,7 @@ Generic options
 Configuration file
 ==================
 
-If `--config=` is not given, `lacme` uses the first existing
-configuration file among *./lacme.conf*,
-*$XDG_CONFIG_HOME/lacme/lacme.conf* (or *~/.config/lacme/lacme.conf* if
-the `XDG_CONFIG_HOME` environment variable is not set), and
-*@@sysconfdir@@/lacme/lacme.conf*.
-Valid options are:
+Valid settings are:
 
 Default section
 ---------------
@@ -143,13 +147,15 @@ Default section
     space-separated list of certificate configuration files or
     directories to use (see the **[certificate configuration
     file](#certificate-configuration-file)** section below for the
-    configuration options).
+    configuration options).  Each item in that list is independently
+    subject to [%-specifier expansion](#percent-specifiers).
 
-    Paths not starting with `/` are relative to the directory name of
-    the **[configuration filename](#configuration-file)**.  The list of
-    files and directories is processed in order, with the later items
-    taking precedence.  Files in a directory are processed in
-    lexicographic order, only considering the ones with suffix `.conf`.
+    Paths not starting with `/` (after %-expansion) are relative to the
+    parent directory of the **[configuration filename](#configuration-file)**.
+    The list of files and directories is processed in the specified
+    order, with the later items taking precedence.  Files in a directory
+    are processed in lexicographic order, only considering the ones with
+    suffix `.conf`.
 
     Default: `lacme-certs.conf lacme-certs.conf.d/`.
 
@@ -162,39 +168,39 @@ of [ACME] commands and dialogues with the remote [ACME] server).
 *socket*
 
 :   See `--socket=`.
-    Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR`
-    environment variable is set.
 
 *user*
 
 :   The username to drop privileges to (setting both effective and real
-    uid).  Preserve root privileges if the value is empty (not
-    recommended).
-    Default: `nobody`.
+    uid).  Skip privilege drop if the value is empty (not recommended).
+    Default: `@@lacme_client_user@@`.
 
 *group*
 
 :   The groupname to drop privileges to (setting both effective and real
     gid, and also setting the list of supplementary gids to that single
-    group).  Preserve root privileges if the value is empty (not
+    group).  Skip privilege drop if the value is empty (not
     recommended).
-    Default: `nogroup`.
+    Default: `@@lacme_client_group@@`.
 
 *command*
 
-:   Path to the [ACME] client executable.
+:   The [ACME] client command.  It is split on whitespace, with the
+    first item being the command to execute, the second its first
+    argument etc.  (Note that `lacme` might append more arguments when
+    executing the command internally.)
     Default: `@@libexecdir@@/lacme/client`.
 
 *server*
 
 :   Root URI of the [ACME] server.
-    Default: `https://acme-v02.api.letsencrypt.org/directory`.
+    Default: `@@acmeapi_server@@`.
 
 *timeout*
 
 :   Timeout in seconds after which the client stops polling the [ACME]
     server and considers the request failed.
-    Default: `10`.
+    Default: `30`.
 
 *SSL_verify*
 
@@ -236,32 +242,40 @@ served during certificate issuance.
 
 *challenge-directory*
 
-:   Specify a non-existent directory under which an external HTTP daemon
-    is configured to serve `GET` requests for challenge files under
-    `/.well-known/acme-challenge/` (for each virtual host requiring
-    authorization) as static files.
-    This option is required when *listen* is empty.
+:   Directory under which an external HTTP daemon is configured to serve `GET`
+    requests for challenge files under `/.well-known/acme-challenge/` (for
+    each virtual host requiring authorization) as static files.
+    The directory _must_ exist beforehand, _must_ be empty, and the
+    lacme client user (by default `@@lacme_client_user@@`) needs to be
+    able to create files under it.
+
+    This setting is required when *listen* is empty.  Moreover its value
+    is subject to [%-specifier expansion](#percent-specifiers) _before_
+    privilege drop.
 
 *user*
 
 :   The username to drop privileges to (setting both effective and real
-    uid).  Preserve root privileges if the value is empty (not
-    recommended).
-    Default: `www-data`.
+    uid).  Skip privilege drop if the value is empty (not recommended).
+    Default: `@@lacme_www_user@@`.
 
 *group*
 
 :   The groupname to drop privileges to (setting both effective and real
     gid, and also setting the list of supplementary gids to that single
-    group).  Preserve root privileges if the value is empty (not
+    group).  Skip privilege drop if the value is empty (not
     recommended).
-    Default: `www-data`.
+    Default: `@@lacme_www_group@@`.
 
 *command*
 
-:   Path to the [ACME] webserver executable.  A separate process is
-    spawned for each address to *listen* on.  (In particular no
-    webserver process is forked when the *listen* option is empty.)
+:   The [ACME] webserver command.  It is split on whitespace, with the
+    first item being the command to execute, the second its first
+    argument etc.  (Note that `lacme` might append more arguments when
+    executing the command internally.)
+    A separate process is spawned for each address to *listen* on.  (In
+    particular no webserver process is forked when the *listen* setting
+    is empty.)
     Default: `@@libexecdir@@/lacme/webserver`.
 
 *iptables*
@@ -269,6 +283,7 @@ served during certificate issuance.
 :   Whether to automatically install temporary [`iptables`(8)] rules to
     open the `ADDRESS[:PORT]` specified with *listen*.  The rules are
     automatically removed once `lacme` exits.
+    This setting is ignored when *challenge-directory* is set.
     Default: `No`.
 
 `[accountd]` section
@@ -283,28 +298,33 @@ UNIX-domain socket.
 *user*
 
 :   The username to drop privileges to (setting both effective and real
-    uid).  Preserve root privileges if the value is empty.
+    uid).  Skip privilege drop if the value is empty (the default).
 
 *group*
 
 :   The groupname to drop privileges to (setting both effective and real
     gid, and also setting the list of supplementary gids to that single
-    group).  Preserve root privileges if the value is empty.
+    group).  Skip privilege drop if the value is empty (the default).
 
 *command*
 
-:   Path to the [`lacme-accountd`(1)] executable.
+:   The [`lacme-accountd`(1)] command.  It is split on whitespace, with
+    the first item being the command to execute, the second its first
+    argument etc.  (Note that `lacme` appends more arguments when
+    executing the command internally.)
+    Each item in that list is independently subject to [%-specifier
+    expansion](#percent-specifiers) _after_ privilege drop.
     Default: `@@bindir@@/lacme-accountd`.
 
-*config*
-
-:   Path to the [`lacme-accountd`(1)] configuration file.
-    Default: `@@sysconfdir@@/lacme/lacme-accountd.conf`.
+    Use for instance `` `ssh -T lacme@account.example.net
+    lacme-accountd` `` in order to spawn a remote [`lacme-accountd`(1)]
+    server.
 
-*privkey*
+*config*
 
-:   The (private) account key to use for signing requests.  See
-    [`lacme-accountd`(1)] for details.
+:   Path to the [`lacme-accountd`(1)] configuration file.  The value is
+    subject to [%-specifier expansion](#percent-specifiers) _after_
+    privilege drop.
 
 *quiet*
 
@@ -317,7 +337,7 @@ For certificate issuances (`newOrder` command), a separate file is used
 to configure paths to the certificate and key, as well as the subject,
 subjectAltName, etc. to generate Certificate Signing Requests.
 Each section denotes a separate certificate issuance.
-Valid options are:
+Valid settings are:
 
 *certificate*
 
@@ -332,11 +352,28 @@ Valid options are:
 
 *certificate-key*
 
-:   Path the service's private key.  This option is required.  The
-    following command can be used to generate a new 4096-bits RSA key in
-    PEM format with mode 0600:
+:   Path to the service's private key.  This setting is required.  The
+    [`genpkey`(1ssl)] command can be used to generate a new service RSA
+    key:
+
+        $ install -vm0600 /dev/null /path/to/service.rsa.key
+        $ openssl genpkey -algorithm RSA -out /path/to/service.rsa.key
+
+    Alternatively, for an ECDSA key using the NIST P-256 curve:
+
+        $ install -vm0600 /dev/null /path/to/service.ecdsa.key
+        $ openssl genpkey -algorithm EC -out /path/to/service.ecdsa.key \
+			-pkeyopt ec_paramgen_curve:P-256 \
+			-pkeyopt ec_param_enc:named_curve
 
-        openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/srv.key
+    `lacme` supports any key algorithm than the underlying libssl
+    (OpenSSL) version is able to manipulate, but the [ACME] server might
+    reject CSRs associated with private keys of deprecated and/or
+    “exotic” algorithms.
+
+    For a dual cert setup (for instance RSA+ECDSA), duplicate the
+    certificate section and use a distinct *certificate-key* resp.
+    *certificate* (or *certificate-chain*) value for each key algorithm.
 
 *min-days*
 
@@ -347,32 +384,43 @@ Valid options are:
     Default: the value of the CLI option `--min-days`, or `21` if there
     is no such option.
 
+*subject*
+
+:   Subject field of the Certificate Signing Request, in the form
+    `/type0=value0/type1=value1/type2=…`.  This setting is required.
+
+*subjectAltName*
+
+:   Comma-separated list of Subject Alternative Names, in the form
+    `type0:value1,type1:value1,type2:…`
+    The only `type` currently supported is `DNS`, to specify an
+    alternative domain name.
+
 *CAfile*
 
-:   Path to trusted issuer certificates, used for validating each issued
-    certificate.  Specifying an empty values skips certificate validation.
+:   Path to the bundle of trusted issuer certificates.  This is used for
+    validating each certificate after issuance or renewal.  Specifying
+    an empty value skips certificate validation.
     Default: `@@datadir@@/lacme/ca-certificates.crt`.
 
 *hash*
 
-:   Message digest algorithm to sign the Certificate Signing Request
-    with.
+:   Message digest to sign the Certificate Signing Request with,
+    overriding the [`req`(1ssl)] default.
 
 *keyUsage*
 
-:   Comma-separated list of Key Usages, see [`x509v3_config`(5ssl)].
+:   Comma-separated list of Key Usages, for instance `digitalSignature,
+    keyEncipherment`, to include in the Certificate Signing Request.
+    See [`x509v3_config`(5ssl)] for a list of possible values.  Note
+    that the ACME server might override the value provided here.
 
-*subject*
-
-:   Subject field of the Certificate Signing Request, in the form
-    `/type0=value0/type1=value1/type2=…`.  This option is required.
+*tlsfeature*
 
-*subjectAltName*
-
-:   Comma-separated list of Subject Alternative Names, in the form
-    `type0:value1,type1:value1,type2:…`
-    The only `type` currently supported is `DNS`, to specify an
-    alternative domain name.
+:   Comma-separated list of [TLS extension][TLS Feature extension]
+    identifiers, such as `status_request` for OCSP Must-Staple.
+    See [`x509v3_config`(5ssl)] for a list of possible values.  Note
+    that the ACME server might override the value provided here.
 
 *chown*
 
@@ -386,16 +434,70 @@ Valid options are:
 
 *notify*
 
-:   Command to pass the the system's command shell (`/bin/sh -c`)
+:   Command to pass the the system's command shell (`` `/bin/sh -c` ``)
     after successful installation of the *certificate* and/or
     *certificate-chain*.
 
+%-specifiers  {#percent-specifiers}
+============
+
+Some CLI options and configuration settings are subject to %-expansion
+for the following specifiers.  Check the documentation of each setting
+to see which ones are affected.
+
+----  ------------------------------------------------------------------
+`%C`  `@@localstatedir@@/cache` for the root user, and `$XDG_CACHE_HOME`
+      for other users (or `$HOME/.cache` if the `XDG_CACHE_HOME`
+      environment variable is unset or empty).
+
+`%E`  `@@sysconfdir@@` for the root user, and `$XDG_CONFIG_HOME` for
+      other users (or `$HOME/.config` if the `XDG_CONFIG_HOME`
+      environment variable is unset or empty).
+
+`%g`  Current group name.
+
+`%G`  Current group ID.
+
+`%h`  Home directory of the current user.
+
+`%t`  `@@runstatedir@@` for the root user, and `$XDG_RUNTIME_DIR` for
+      other users.  Non-root users may only use `%t` when the
+      `XDG_RUNTIME_DIR` environment variable is set to a non-empty
+      value.
+
+`%T`  `$TMPDIR`, or `/tmp` if the `TMPDIR` environment variable is unset
+      or empty.
+
+`%u`  Current user name.
+
+`%U`  Current user ID.
+
+`%%`  A literal `%`.
+----  ------------------------------------------------------------------
+
 Examples
 ========
 
-    ~$ sudo lacme account --register --tos-agreed mailto:noreply@example.com
-    ~$ sudo lacme newOrder
-    ~$ sudo lacme revokeCert /path/to/server/certificate.pem
+    $ sudo lacme account --register --tos-agreed mailto:noreply@example.com
+    $ sudo lacme newOrder
+    $ sudo lacme revokeCert /path/to/service.crt
+
+Automatic renewal can be scheduled via [`crontab`(5)] or
+[`systemd.timer`(5)].  In order to avoid deploying a single account key
+onto multiple nodes and/or dealing with multiple account keys, one can
+install a single [`lacme-accountd`(1)] instance on a dedicated host,
+generate a single account key there (and keep it well), and set the
+following in the [`[accountd]` section](#accountd-section):
+
+    command = ssh -T lacme@account.example.net lacme-accountd
+
+If the user running `lacme` can connect to `lacme@account.example.net`
+using (passwordless) key authentication, this setting will spawn a
+remote [`lacme-accountd`(1)] and use it to sign [ACME] requests.
+Further hardening can be achieved by means of [`authorized_keys`(5)]
+restrictions:
+
+    restrict,from="…",command="/usr/bin/lacme-accountd --quiet --stdio" ssh-rsa …
 
 See also
 ========
@@ -403,7 +505,13 @@ See also
 [`lacme-accountd`(1)]
 
 [ACME]: https://tools.ietf.org/html/rfc8555
+[TLS Feature extension]: https://tools.ietf.org/html/rfc7633
 [`lacme-accountd`(1)]: lacme-accountd.1.html
 [`iptables`(8)]: https://linux.die.net/man/8/iptables
-[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
-[`x509v3_config`(5ssl)]: https://www.openssl.org/docs/manmaster/apps/x509v3_config.html
+[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html
+[`x509v3_config`(5ssl)]: https://www.openssl.org/docs/manmaster/man5/x509v3_config.html
+[`genpkey`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-genpkey.html
+[`req`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-req.html
+[`crontab`(5)]: https://linux.die.net/man/5/crontab
+[`systemd.timer`(5)]: https://www.freedesktop.org/software/systemd/man/systemd.timer.html
+[`authorized_keys`(5)]: https://man.openbsd.org/sshd.8#AUTHORIZED_KEYS_FILE_FORMAT