diff options
Diffstat (limited to 'lacme.8.md')
| -rw-r--r-- | lacme.8.md | 278 |
1 files changed, 193 insertions, 85 deletions
@@ -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 |