From c93443364ce23ced97a80bfda8f8bb35ec19fcdb Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 9 Dec 2020 19:02:44 +0100 Subject: documentation: suggest to generate private key material with genpkey(1ssl). * Also suggest a command to generate an ECDSA key not just RSA. * Hint at which key algorithms are supported. --- lacme-accountd.1.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index a967b67..24e73eb 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -55,10 +55,13 @@ Options * `gpg:`*FILE*, to specify a [`gpg`(1)]-encrypted private key (in PEM format). - The following command can be used to generate a new 4096-bits RSA - key in PEM format with mode 0600: + The [`genpkey`(1ssl)] command can be used to generate a new private + (account) key: - openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/account.key + $ install -vm0600 /dev/null /path/to/account.key + $ openssl genpkey -algorithm RSA -out /path/to/account.key + + Currently `lacme-accountd` only supports RSA account keys. `--socket=`*path* @@ -141,3 +144,4 @@ See also [`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html [OpenSSH]: https://www.openssh.com/ [`ssh`(1)]: https://man.openbsd.org/ssh +[`genpkey`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-genpkey.html -- cgit v1.2.3 From f4b7c7b6130722535cb87c123d11ba554e7806c7 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 9 Dec 2020 19:20:13 +0100 Subject: wibble --- lacme-accountd.1.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 24e73eb..359a6d1 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -120,17 +120,17 @@ Examples Run `lacme-accountd` in a first terminal: - ~$ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme + $ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme Then, while `lacme-accountd` is running, execute locally [`lacme`(8)] in another terminal: - ~$ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder + $ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder Alternatively, use [OpenSSH] 6.7 or later to forward the socket and execute [`lacme`(8)] remotely: - ~$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:$XDG_RUNTIME_DIR/S.lacme user@example.org \ + $ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:$XDG_RUNTIME_DIR/S.lacme user@example.org \ sudo lacme --socket=/path/to/remote.sock newOrder See also -- cgit v1.2.3 From e8980fb172221cbffd7fa672d65da0a806524e72 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 9 Dec 2020 19:36:06 +0100 Subject: documentation: clarify that "file:/path/to/account.key" can point to a symmetrically-encrypted private key. --- lacme-accountd.1.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 359a6d1..560cfac 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -45,15 +45,14 @@ Options file](#configuration-file)** section below for the configuration options. -`--privkey=`*arg* +`--privkey=`*value* : Specify the (private) account key to use for signing requests. - Currently supported *arg*uments are: + Currently supported *value*s are: - * `file:`*FILE*, to specify an encrypted private key (in PEM - format); and - * `gpg:`*FILE*, to specify a [`gpg`(1)]-encrypted private key (in - PEM format). + * `file:`*FILE*, for a private key in PEM format (optionally + symmetrically encrypted) + * `gpg:`*FILE*, for a [`gpg`(1)]-encrypted private key The [`genpkey`(1ssl)] command can be used to generate a new private (account) key: -- cgit v1.2.3 From 2efd4458f4db7f489ecc81f4039b8e8103edf9d9 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Tue, 16 Feb 2021 17:24:31 +0100 Subject: Don't load configuration files from ./ by default. This is a breaking change: lacme(8) resp. lacme-accountd(1) no longer consider ./lacme.conf resp. ./lacme-accountd.conf as default location for the configuration file. Doing so has security implications when running these program from insecure directories. --- lacme-accountd.1.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 560cfac..e628476 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -84,10 +84,10 @@ Configuration file ================== If `--config=` is not given, `lacme-accountd` uses the first existing -configuration file among *./lacme-accountd.conf*, -*$XDG_CONFIG_HOME/lacme/lacme-accountd.conf* (or -*~/.config/lacme/lacme-accountd.conf* if the `XDG_CONFIG_HOME` -environment variable is not set), and *@@sysconfdir@@/lacme/lacme-accountd.conf*. +configuration file among *$XDG_CONFIG_HOME/lacme/lacme-accountd.conf* +(or *~/.config/lacme/lacme-accountd.conf* if the `XDG_CONFIG_HOME` +environment variable is not set), and +*@@sysconfdir@@/lacme/lacme-accountd.conf*. When given on the command line, the `--privkey=`, `--socket=` and `--quiet` options take precedence over their counterpart (without -- cgit v1.2.3 From 3e49ef22ba3fbbe4e73bc4ad151770603ffa5ef1 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 19 Feb 2021 18:52:33 +0100 Subject: lacme-accountd: Don't error out when the default configuration file is missing. Instead, treat it as an empty file. This makes it possible to use lacme-accountd(1) without configuration file under ~/.config/lacme. --- lacme-accountd.1.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index e628476..5303418 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -41,9 +41,12 @@ Options `--config=`*filename* -: Use *filename* as configuration file. See the **[configuration - file](#configuration-file)** section below for the configuration - options. +: Use *filename* as configuration file. `lacme-accountd` fails when + `--config=` is used with a non-existent file, but a non-existent + default location is treated as if it were an empty file. + + See the **[configuration file](#configuration-file)** section below + for the configuration options. `--privkey=`*value* -- cgit v1.2.3 From 57afbf387cf812945ad14cd03570b0746fc4c865 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 18 Feb 2021 12:22:37 +0100 Subject: Document spawning a remote lacme-accountd(1) instance. And add a test case for this. --- lacme-accountd.1.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 5303418..9377e23 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -135,6 +135,10 @@ execute [`lacme`(8)] remotely: $ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:$XDG_RUNTIME_DIR/S.lacme user@example.org \ sudo lacme --socket=/path/to/remote.sock newOrder +Consult the [`lacme`(8) manual][`lacme`(8)] for a solution involving +connecting to `lacme-accountd` on a dedicated remote host. Doing so +enables automatic renewal via [`crontab`(5)] or [`systemd.timer`(5)]. + See also ======== @@ -147,3 +151,5 @@ See also [OpenSSH]: https://www.openssh.com/ [`ssh`(1)]: https://man.openbsd.org/ssh [`genpkey`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-genpkey.html +[`crontab`(5)]: https://linux.die.net/man/5/crontab +[`systemd.timer`(5)]: https://www.freedesktop.org/software/systemd/man/systemd.timer.html -- cgit v1.2.3 From 4a502836164821b9faa56d363c8fb116ce032321 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 19 Feb 2021 18:11:09 +0100 Subject: Wording: s/option/setting/. --- lacme-accountd.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 9377e23..cd6352c 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -94,11 +94,11 @@ environment variable is not set), and When given on the command line, the `--privkey=`, `--socket=` and `--quiet` options take precedence over their counterpart (without -leading `--`) in the configuration file. Valid options are: +leading `--`) in the configuration file. Valid settings are: *privkey* -: See `--privkey=`. This option is required when `--privkey=` is not +: See `--privkey=`. This setting is required when `--privkey=` is not specified on the command line. *gpg* -- cgit v1.2.3 From 0ef94d85e58497dcb2c4c954cadcac918032467a Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 18 Feb 2021 21:07:01 +0100 Subject: Add %-specifiers support. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit lacme(8): for --config=, --socket=, --config-certs= (and ‘socket’/ ‘config-certs’/‘challenge-directory’ configuration options *before* privilege drop; and for the [accountd] section ‘command’/‘config’ configuration options *after* privilege drop). lacme-accountd(1): for --config=, --socket= and --privkey= (and ‘socket’/‘privkey’ configuration options). This also changes the default configuration file location. lacme(8) and lacme-accountd(1) now respectively use /etc/lacme/lacme.conf resp. /etc/lacme/lacme-accountd.conf when running as root, and $XDG_CONFIG_HOME/lacme/lacme.conf resp. $XDG_CONFIG_HOME/lacme/lacme-accountd.conf when running as a normal user. There is no fallback to /etc anymore. --- lacme-accountd.1.md | 67 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 53 insertions(+), 14 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index cd6352c..4c494f2 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -41,9 +41,12 @@ Options `--config=`*filename* -: Use *filename* as configuration file. `lacme-accountd` fails when - `--config=` is used with a non-existent file, but a non-existent - default location is treated as if it were an empty file. +: Use *filename* as configuration file instead of + `%E/lacme/lacme-accountd.conf`. The value is subject to + [%-specifier expansion](#percent-specifiers). `lacme-accountd` + fails when `--config=` is used with a non-existent file, but a + non-existent default location is treated as if it were an empty + file. See the **[configuration file](#configuration-file)** section below for the configuration options. @@ -57,6 +60,8 @@ Options symmetrically encrypted) * `gpg:`*FILE*, for a [`gpg`(1)]-encrypted private key + *FILE* is subject to [%-specifier expansion](#percent-specifiers). + The [`genpkey`(1ssl)] command can be used to generate a new private (account) key: @@ -67,9 +72,14 @@ Options `--socket=`*path* -: Use *path* as the UNIX-domain socket to bind against for signature - requests from the [ACME] client. `lacme-accountd` aborts if *path* - exists or if its parent directory is writable by other users. +: Use *path* as the UNIX-domain socket to bind to for signature + requests from the [ACME] client. The value is subject to + [%-specifier expansion](#percent-specifiers). `lacme-accountd` + aborts if *path* exists or if its parent directory is writable by + other users. + Default: `%t/S.lacme` (omitting `--socket=` therefore yields an + error when `lacme-accountd` doesn't run as and the `XDG_RUNTIME_DIR` + environment variable is unset or empty). `-h`, `--help` @@ -86,12 +96,6 @@ Options Configuration file ================== -If `--config=` is not given, `lacme-accountd` uses the first existing -configuration file among *$XDG_CONFIG_HOME/lacme/lacme-accountd.conf* -(or *~/.config/lacme/lacme-accountd.conf* if the `XDG_CONFIG_HOME` -environment variable is not set), and -*@@sysconfdir@@/lacme/lacme-accountd.conf*. - When given on the command line, the `--privkey=`, `--socket=` and `--quiet` options take precedence over their counterpart (without leading `--`) in the configuration file. Valid settings are: @@ -110,13 +114,48 @@ leading `--`) in the configuration file. Valid settings are: *socket* : See `--socket=`. - Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR` - environment variable is set. *quiet* : Be quiet. Possible values: `Yes`/`No`. +%-specifiers {#percent-specifiers} +============ + +The value the `--config=`, `--privkey=` and `--socket=` CLI options (and +*privkey* and *socket* configuration options) are subject to %-expansion +for the following specifiers. + +---- ------------------------------------------------------------------ +`%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 ======== -- cgit v1.2.3 From 8e612e071b8c0fc99ebf91673f53ca5f0d6bdd11 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sat, 20 Feb 2021 19:56:15 +0100 Subject: Document `lacme-accountd --stdio`. It's an internal flag, but can be useful for authorized_keys(5) restrictions. --- lacme-accountd.1.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 4c494f2..476a150 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -81,6 +81,14 @@ Options error when `lacme-accountd` doesn't run as and the `XDG_RUNTIME_DIR` environment variable is unset or empty). +`--stdio` + +: Read signature requests from the standard input and write signatures + to the standard output, instead of using a UNIX-domain socket for + communication with the [ACME] client. + This _internal_ flag should never be used by standalone + `lacme-accountd` instances, only for those [`lacme`(8)] spawns. + `-h`, `--help` : Display a brief help and exit. -- cgit v1.2.3 From 74c0a11722cf1e01b9a9834e89a07b55eaf01080 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sat, 20 Feb 2021 22:05:18 +0100 Subject: lacme-accountd: new setting 'logfile' to log signature requests. Prefixed with a timestamp. --- lacme-accountd.1.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 476a150..66ef222 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -119,6 +119,11 @@ leading `--`) in the configuration file. Valid settings are: [`gpg`(1)] to use, as well as some default options. Default: `gpg --quiet`. +*logfile* + +: An optional file where to log to. The value is subject to + [%-specifier expansion](#percent-specifiers). + *socket* : See `--socket=`. @@ -131,8 +136,8 @@ leading `--`) in the configuration file. Valid settings are: ============ The value the `--config=`, `--privkey=` and `--socket=` CLI options (and -*privkey* and *socket* configuration options) are subject to %-expansion -for the following specifiers. +*privkey*, *socket* and *logfile* settings in the configuration file) +are subject to %-expansion for the following specifiers. ---- ------------------------------------------------------------------ `%C` `@@localstatedir@@/cache` for the root user, and `$XDG_CACHE_HOME` -- cgit v1.2.3 From 594c32ac58167396980a404261047e94155a83d3 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sun, 21 Feb 2021 13:01:14 +0100 Subject: wording --- lacme-accountd.1.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index 66ef222..d0b2c6b 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -136,8 +136,9 @@ leading `--`) in the configuration file. Valid settings are: ============ The value the `--config=`, `--privkey=` and `--socket=` CLI options (and -*privkey*, *socket* and *logfile* settings in the configuration file) -are subject to %-expansion for the following specifiers. +also the *privkey*, *socket* and *logfile* settings from the +configuration file) are subject to %-expansion for the following +specifiers. ---- ------------------------------------------------------------------ `%C` `@@localstatedir@@/cache` for the root user, and `$XDG_CACHE_HOME` -- cgit v1.2.3 From 9898b1877ce2973bbc336921969bd7f16d3698fa Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sun, 21 Feb 2021 18:49:14 +0100 Subject: lacme-accountd(1): new setting 'keyid'. This saves a round trip and provides a safeguard against malicious clients. --- lacme-accountd.1.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) (limited to 'lacme-accountd.1.md') diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md index d0b2c6b..4933a78 100644 --- a/lacme-accountd.1.md +++ b/lacme-accountd.1.md @@ -119,14 +119,28 @@ leading `--`) in the configuration file. Valid settings are: [`gpg`(1)] to use, as well as some default options. Default: `gpg --quiet`. +*socket* + +: See `--socket=`. + *logfile* : An optional file where to log to. The value is subject to [%-specifier expansion](#percent-specifiers). -*socket* +*keyid* -: See `--socket=`. +: The "Key ID", as shown by `` `acme account` ``, to give the [ACME] + client. With an empty *keyid* (the default) the client forwards the + JSON Web Key (JWK) to the [ACME] server to retrieve the correct + value. A non-empty value therefore saves a round-trip. + + A non-empty value also causes `lacme-accountd` to send an empty JWK, + thereby revoking all account management access (status change, + contact address updates etc.) from the client: any `` `acme account` `` + command (or any command from [`lacme`(8)] before version 0.8.0) is + bound to be rejected by the [ACME] server. This provides a + safeguard against malicious clients. *quiet* -- cgit v1.2.3