From 615f98315ce17751a703d4933ae690befdae82e1 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 3 Aug 2020 21:58:25 +0200 Subject: Makefile: Major refactoring, add install and uninstall targets. Honor BUILD_DOCDIR and DESTDIR variables. --- Changelog | 8 +- Makefile | 59 +++++--- fixman.jq | 26 ---- lacme-accountd.1.md | 143 ++++++++++++++++++ lacme-accountd.md | 143 ------------------ lacme.1.md | 413 ++++++++++++++++++++++++++++++++++++++++++++++++++++ lacme.md | 413 ---------------------------------------------------- pandoc2man.jq | 28 ++++ 8 files changed, 624 insertions(+), 609 deletions(-) delete mode 100755 fixman.jq create mode 100644 lacme-accountd.1.md delete mode 100644 lacme-accountd.md create mode 100644 lacme.1.md delete mode 100644 lacme.md create mode 100755 pandoc2man.jq diff --git a/Changelog b/Changelog index 2010c52..6aa31e8 100644 --- a/Changelog +++ b/Changelog @@ -1,8 +1,10 @@ lacme (0.7) UNRELEASED; - + Default listening socket for the webserver component is now - /run/lacme-www.socket. (It was previously under the legacy directory - /var/run.) + + Default listening socket for the webserver component is now + /run/lacme-www.socket. (It was previously under the legacy directory + /var/run.) + * Makefile: major refactoring, add install and uninstall targets, honor + BUILD_DOCDIR and DESTDIR variables. -- Guilhem Moulin Thu, 22 Aug 2019 00:31:35 +0200 diff --git a/Makefile b/Makefile index 0aa3046..6bfa739 100644 --- a/Makefile +++ b/Makefile @@ -1,30 +1,41 @@ -MANPAGES = lacme-accountd.1 lacme.1 +DESTDIR ?= /usr/local +BUILD_DOCDIR ?= . +MANUAL_FILES = $(addprefix $(BUILD_DOCDIR)/,$(patsubst ./%.md,%,$(wildcard ./*.[1-9].md))) -all: ${MANPAGES} +all: manual +doc: manual + +manual: $(MANUAL_FILES) # upper case the headers and remove the links -%.1: %.md - @pandoc -f markdown -t json "$<" | \ - jq -f fixman.jq | \ - pandoc -s -f json -t man+smart -o "$@" - -install: ${MANPAGES} - install -d $(DESTDIR)/etc/lacme - install -d $(DESTDIR)/etc/lacme/lacme-certs.conf.d - install -m0644 -t $(DESTDIR)/etc/lacme config/*.conf - install -m0644 -t $(DESTDIR)/etc/lacme snippets/*.conf - install -d $(DESTDIR)/usr/share/lacme - install -m0644 -t $(DESTDIR)/usr/share/lacme certs/lets-encrypt-x[1-4]-cross-signed.pem - install -d $(DESTDIR)/usr/lib/lacme - install -m0755 -t $(DESTDIR)/usr/lib/lacme client webserver - install -d $(DESTDIR)/usr/share/man/man1 - install -m0644 -t $(DESTDIR)/usr/share/man/man1 lacme-accountd.1 lacme.1 - install -d $(DESTDIR)/usr/bin - install -m0644 -t $(DESTDIR)/usr/bin lacme-accountd - install -d $(DESTDIR)/usr/sbin - install -m0644 -t $(DESTDIR)/usr/bin lacme +$(MANUAL_FILES): $(BUILD_DOCDIR)/%: ./%.md + pandoc -f markdown -t json -- "$<" | ./pandoc2man.jq | pandoc -s -f json -t man -o "$@" + +prefix ?= $(DESTDIR) +exec_prefix ?= $(prefix) +bindir ?= $(exec_prefix)/bin +sbindir ?= $(exec_prefix)/sbin +libexecdir ?= $(exec_prefix)/lib +datarootdir ?= $(prefix)/share +sysconfdir ?= $(prefix)/etc +mandir ?= $(datarootdir)/man +man1dir ?= $(mandir)/man1 + +install: all + install -m0644 -vDt $(sysconfdir)/lacme config/*.conf snippets/*.conf + install -vd $(sysconfdir)/lacme/lacme-certs.conf.d + install -m0644 -vDt $(datarootdir)/lacme certs/lets-encrypt-x[1-4]-cross-signed.pem + install -m0755 -vDt $(libexecdir)/lacme ./client ./webserver + install -m0644 -vDt $(man1dir) $(BUILD_DOCDIR)/lacme-accountd.1 $(BUILD_DOCDIR)/lacme.1 + install -m0644 -vDt $(bindir) ./lacme-accountd + install -m0644 -vDt $(sbindir) ./lacme + +uninstall: + rm -vf -- $(bindir)/lacme-accountd $(sbindir)/lacme + rm -vf -- $(man1dir)/lacme-accountd.1 $(man1dir)/lacme.1 + rm -rvf -- $(sysconfdir)/lacme $(datarootdir)/lacme $(libexecdir)/lacme clean: - rm -vf ${MANPAGES} + rm -vf -- $(MANUAL_FILES) -.PHONY: all install clean +.PHONY: all doc manual install uninstall clean diff --git a/fixman.jq b/fixman.jq deleted file mode 100755 index 3524420..0000000 --- a/fixman.jq +++ /dev/null @@ -1,26 +0,0 @@ -#!/usr/bin/jq -f -def fixheaders: - if .t == "Header" then - .c[2][] |= (if .t == "Str" then .c |= ascii_upcase else . end) - else - . - end; - -def fixlinks: - if type == "object" then - if .t == "Link" then - if .c[2][0][0:7] == "mailto:" then . else .c[1][] end - else - map_values(fixlinks) - end - else if type == "array" then - map(fixlinks) - else - . - end - end; - -{ "pandoc-api-version" -, meta -, blocks: .blocks | map(fixheaders) | map(fixlinks) -} diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md new file mode 100644 index 0000000..403c68c --- /dev/null +++ b/lacme-accountd.1.md @@ -0,0 +1,143 @@ +% lacme-accountd(1) +% [Guilhem Moulin](mailto:guilhem@fripost.org) +% March 2016 + +Name +==== + +lacme-accountd - [ACME] client written with process isolation and +minimal privileges in mind (account key manager) + +Synopsis +======== + +`lacme-accountd` [`--config=FILENAME`] [`--privkey=ARG`] [`--socket=PATH`] [`--quiet`] + +Description +=========== + +`lacme-accountd` is the account key manager component of [`lacme`(1)], a +small [ACME] client written with process isolation and minimal +privileges in mind. No other [`lacme`(1)] component needs access to the +account key; in fact the account key could as well be stored on another +host or a smartcard. + +`lacme-accountd` binds to a UNIX-domain socket (specified with +`--socket=`), which [ACME] clients can connect to in order to request +data signatures. +As a consequence, `lacme-accountd` needs to be up and running before +using [`lacme`(1)] to issue [ACME] commands. Also, the process does not +automatically terminate after the last signature request: instead, one +sends an `INT` or `TERM` [`signal`(7)] to bring the server down. + +Furthermore, one can use the UNIX-domain socket forwarding facility of +[OpenSSH] 6.7 and later to run `lacme-accountd` and [`lacme`(1)] on +different hosts. For instance one could store the account key on a +machine that is not exposed to the internet. See the +**[examples](#examples)** section below. + +Options +======= + +`--config=`*filename* + +: Use *filename* as configuration file. See the **[configuration + file](#configuration-file)** section below for the configuration + options. + +`--privkey=`*arg* + +: Specify the (private) account key to use for signing requests. + Currently supported *arg*uments 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). + + The following command can be used to generate a new 4096-bits RSA + key in PEM format with mode 0600: + + openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/account.key + +`--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. + +`-h`, `--help` + +: Display a brief help and exit. + +`-q`, `--quiet` + +: Be quiet. + +`--debug` + +: Turn on debug mode. + +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 */etc/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 options are: + +*privkey* + +: See `--privkey=`. This option is required when `--privkey=` is not + specified on the command line. + +*gpg* + +: For a [`gpg`(1)]-encrypted private account key, specify the binary + [`gpg`(1)] to use, as well as some default options. + Default: `gpg --quiet`. + +*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`. + +Examples +======== + +Run `lacme-accountd` in a first terminal: + + ~$ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme + +Then, while `lacme-accountd` is running, execute locally [`lacme`(1)] in +another terminal: + + ~$ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder + +Alternatively, use [OpenSSH] 6.7 or later to forward the socket and +execute [`lacme`(1)] 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 + +See also +======== + +[`lacme`(1)], [`ssh`(1)] + +[ACME]: https://tools.ietf.org/html/rfc8555 +[`lacme`(1)]: lacme.1.html +[`signal`(7)]: http://linux.die.net/man/7/signal +[`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html +[OpenSSH]: http://www.openssh.com/ +[`ssh`(1)]: http://man.openbsd.org/ssh diff --git a/lacme-accountd.md b/lacme-accountd.md deleted file mode 100644 index 403c68c..0000000 --- a/lacme-accountd.md +++ /dev/null @@ -1,143 +0,0 @@ -% lacme-accountd(1) -% [Guilhem Moulin](mailto:guilhem@fripost.org) -% March 2016 - -Name -==== - -lacme-accountd - [ACME] client written with process isolation and -minimal privileges in mind (account key manager) - -Synopsis -======== - -`lacme-accountd` [`--config=FILENAME`] [`--privkey=ARG`] [`--socket=PATH`] [`--quiet`] - -Description -=========== - -`lacme-accountd` is the account key manager component of [`lacme`(1)], a -small [ACME] client written with process isolation and minimal -privileges in mind. No other [`lacme`(1)] component needs access to the -account key; in fact the account key could as well be stored on another -host or a smartcard. - -`lacme-accountd` binds to a UNIX-domain socket (specified with -`--socket=`), which [ACME] clients can connect to in order to request -data signatures. -As a consequence, `lacme-accountd` needs to be up and running before -using [`lacme`(1)] to issue [ACME] commands. Also, the process does not -automatically terminate after the last signature request: instead, one -sends an `INT` or `TERM` [`signal`(7)] to bring the server down. - -Furthermore, one can use the UNIX-domain socket forwarding facility of -[OpenSSH] 6.7 and later to run `lacme-accountd` and [`lacme`(1)] on -different hosts. For instance one could store the account key on a -machine that is not exposed to the internet. See the -**[examples](#examples)** section below. - -Options -======= - -`--config=`*filename* - -: Use *filename* as configuration file. See the **[configuration - file](#configuration-file)** section below for the configuration - options. - -`--privkey=`*arg* - -: Specify the (private) account key to use for signing requests. - Currently supported *arg*uments 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). - - The following command can be used to generate a new 4096-bits RSA - key in PEM format with mode 0600: - - openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/account.key - -`--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. - -`-h`, `--help` - -: Display a brief help and exit. - -`-q`, `--quiet` - -: Be quiet. - -`--debug` - -: Turn on debug mode. - -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 */etc/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 options are: - -*privkey* - -: See `--privkey=`. This option is required when `--privkey=` is not - specified on the command line. - -*gpg* - -: For a [`gpg`(1)]-encrypted private account key, specify the binary - [`gpg`(1)] to use, as well as some default options. - Default: `gpg --quiet`. - -*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`. - -Examples -======== - -Run `lacme-accountd` in a first terminal: - - ~$ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme - -Then, while `lacme-accountd` is running, execute locally [`lacme`(1)] in -another terminal: - - ~$ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder - -Alternatively, use [OpenSSH] 6.7 or later to forward the socket and -execute [`lacme`(1)] 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 - -See also -======== - -[`lacme`(1)], [`ssh`(1)] - -[ACME]: https://tools.ietf.org/html/rfc8555 -[`lacme`(1)]: lacme.1.html -[`signal`(7)]: http://linux.die.net/man/7/signal -[`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html -[OpenSSH]: http://www.openssh.com/ -[`ssh`(1)]: http://man.openbsd.org/ssh diff --git a/lacme.1.md b/lacme.1.md new file mode 100644 index 0000000..5d86f40 --- /dev/null +++ b/lacme.1.md @@ -0,0 +1,413 @@ +% lacme(1) +% [Guilhem Moulin](mailto:guilhem@fripost.org) +% December 2015 + +Name +==== + +lacme - [ACME] client written with process isolation and minimal +privileges in mind + +Synopsis +======== + +`lacme` [`--config=FILENAME`] [`--socket=PATH`] [*OPTION* …] *COMMAND* [*ARGUMENT* …] + +Description +=========== + +`lacme` is a small [ACME] client written with process isolation and +minimal privileges in mind. It is divided into four components, each +with its own executable: + + 1. A [`lacme-accountd`(1)] process to manage the account key and issue + SHA-256 signatures needed for each [ACME] command. (This process + binds to a UNIX-domain socket to reply to signature requests from + the [ACME] client.) + One can use the UNIX-domain socket forwarding facility of OpenSSH + 6.7 and later to run [`lacme-accountd`(1)] and `lacme` on different + hosts. Alternatively, the [`lacme-accountd`(1)] process can be + spawned by the “master” `lacme` process below; in that case, the + two processes communicate through a socket pair. + + 2. A “master” `lacme` process, which runs as root and is the only + component with access to the private key material of the server + keys. It is used to fork the [ACME] client (and optionally the + [ACME] webserver) after dropping root privileges. + 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. + + 3. An actual [ACME] client (specified with the *command* option of the + [`[client]` section](#client-section) of the configuration file), + which builds [ACME] commands and dialogues with the remote [ACME] + server. + Since [ACME] commands need to be signed with the account key, the + “master” `lacme` process passes the [`lacme-accountd`(1)] + UNIX-domain socket to the [ACME] client: data signatures are + 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]` + 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 + answer challenges.) That webserver only processes `GET` and `HEAD` + requests under the `/.well-known/acme-challenge/` URI. + Moreover temporary [`iptables`(8)] rules can be automatically + installed to open the HTTP port. + +Commands +======== + +`lacme account` [`--tos-agreed`] [`--register`] [*CONTACT* …] + +: Register (if `--registered` is set) a [`lacme-accountd`(1)]-managed + account key. A list of *CONTACT* information (such as `maito:` + URIs) can be specified in order for the [ACME] server to contact the + client for issues related to this registration (such as + notifications about server-initiated revocations). `--tos-agreed` + indicates agreement with the [ACME] server's Terms of Service (and + might be required for registration). + + If the account key is already registered, update the contact info + with the given list of *CONTACT* information. + + Upon success, `lacme` prints the new or updated Account Object from + the [ACME] server. + +`lacme` [`--config-certs=`*FILE*] [`--min-days=`*INT*] `newOrder` [*SECTION* …] + +: Read the certificate configuration *FILE* (see the **[certificate + configuration file](#certificate-configuration-file)** section below + for the configuration options), and request new Certificate Issuance + for each of its sections (or the given list of *SECTION*s). + Command alias: `new-order`. + +`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. + Command alias: `revoke-cert`. + +Generic options +=============== + +`--config=`*filename* + +: Use *filename* as configuration file. 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 + [`[client]` section](#client-section) of the configuration file. + Moreover this option is ignored when the configuration file has an + [`[accountd]` section](#accountd-section); in that case `lacme` + spawns [`lacme-accountd`(1)], and the two processes communicate + through a socket pair. + +`-h`, `--help` + +: Display a brief help and exit. + +`-q`, `--quiet` + +: Be quiet. + +`--debug` + +: Turn on debug mode. + +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 +*/etc/lacme/lacme.conf*. +Valid options are: + +Default section +--------------- + +*config-certs* + +: For certificate issuances (`newOrder` command), specify the + 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). + + 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`. + + Default: `lacme-certs.conf lacme-certs.conf.d/`. + +`[client]` section +------------------ + +This section is used for configuring the [ACME] client (which takes care +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`. + +*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 + recommended). + Default: `nogroup`. + +*command* + +: Path to the [ACME] client executable. + Default: `/usr/lib/lacme/client`. + +*server* + +: Root URI of the [ACME] server. + Default: `https://acme-v02.api.letsencrypt.org/directory`. + +*timeout* + +: Timeout in seconds after which the client stops polling the [ACME] + server and considers the request failed. + Default: `10`. + +*SSL_verify* + +: Whether to verify the server certificate chain. + Default: `Yes`. + +*SSL_version* + +: Specify the version of the SSL protocol used to transmit data. + +*SSL_cipher_list* + +: Specify the cipher list for the connection, see [`ciphers`(1ssl)] + for more information. + +`[webserver]` section +--------------------- + +This section is used to configure how [ACME] challenge responses are +served during certificate issuance. + +*listen* + +: Comma- or space-separated list of addresses to listen on. Valid + addresses are of the form `IPV4:PORT`, `[IPV6]:PORT` (where the + `:PORT` suffix is optional and defaults to the HTTP port 80), or an + absolute path of a UNIX-domain socket (created with mode `0666`). + Default: `/run/lacme-www.socket`. + + **Note**: The default value is only suitable when an external HTTP + daemon is publicly reachable and passes all ACME challenge requests + to the webserver component through the UNIX-domain socket + `/run/lacme-www.socket` (for instance using the provided + `/etc/lacme/apache2.conf` or `/etc/lacme/nginx.conf` configuration + snippets for each virtual host requiring authorization). If there + is no HTTP daemon bound to port 80 one needs to set *listen* to + `[::]` (or `0.0.0.0 [::]` when dual IPv4/IPv6 stack is disabled or + unavailable), and possibly also set *iptables* to `Yes`. + +*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. + +*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`. + +*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 + recommended). + Default: `www-data`. + +*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.) + Default: `/usr/lib/lacme/webserver`. + +*iptables* + +: Whether to automatically install temporary [`iptables`(8)] rules to + open the `ADDRESS[:PORT]` specified with *listen*. The rules are + automatically removed once `lacme` exits. + Default: `No`. + +`[accountd]` section +--------------------- + +This section is used for configuring the [`lacme-accountd`(1)] process. +If the section (including its header) is absent or commented out, +`lacme` connects to an existing UNIX-domain socket bound by a running +[`lacme-accountd`(1)] process. + +*user* + +: The username to drop privileges to (setting both effective and real + uid). Preserve root privileges if the value is empty. + +*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. + +*command* + +: Path to the [`lacme-accountd`(1)] executable. + Default: `/usr/bin/lacme-accountd`. + +*config* + +: Path to the [`lacme-accountd`(1)] configuration file. + Default: `/etc/lacme/lacme-accountd.conf`. + +*privkey* + +: The (private) account key to use for signing requests. See + [`lacme-accountd`(1)] for details. + +*quiet* + +: Be quiet. Possible values: `Yes`/`No`. + +Certificate configuration file +============================== + +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: + +*certificate* + +: Where to store the issued certificate (in PEM format). + At least one of *certificate* or *certificate-chain* is required. + +*certificate-chain* + +: Where to store the issued certificate, concatenated with the content + of the file specified specified with the *CAfile* option (in PEM + format). + At least one of *certificate* or *certificate-chain* is required. + +*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: + + openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/srv.key + +*min-days* + +: For an existing certificate, the minimum number of days before its + expiration date the section is considered for re-issuance. + A negative value forces reissuance, while the number `0` limits + reissuance to expired certificates. + Default: the value of the CLI option `--min-days`, or `21` if there + is no such option. + +*CAfile* + +: Path to the issuer's certificate. This is used for + *certificate-chain* and to verify the validity of each issued + certificate. + Specifying an empty value skip certificate validation. + Default: `/usr/share/lacme/lets-encrypt-x3-cross-signed.pem`. + +*hash* + +: Message digest algorithm to sign the Certificate Signing Request + with. + +*keyUsage* + +: Comma-separated list of Key Usages, see [`x509v3_config`(5ssl)]. + +*subject* + +: Subject field of the Certificate Signing Request, in the form + `/type0=value0/type1=value1/type2=…`. This option 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. + +*chown* + +: An optional `username[:groupname]` to chown the issued *certificate* + and *certificate-chain* to. + +*chmod* + +: An optional octal mode to chmod the issued *certificate* and + *certificate-chain* to. + +*notify* + +: Command to pass the the system's command shell (`/bin/sh -c`) + after successful installation of the *certificate* and/or + *certificate-chain*. + +Examples +======== + + ~$ sudo lacme account --register --tos-agreed mailto:noreply@example.com + ~$ sudo lacme newOrder + ~$ sudo lacme revokeCert /path/to/server/certificate.pem + +See also +======== + +[`lacme-accountd`(1)] + +[ACME]: https://tools.ietf.org/html/rfc8555 +[`lacme-accountd`(1)]: lacme-accountd.1.html +[`iptables`(8)]: http://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 diff --git a/lacme.md b/lacme.md deleted file mode 100644 index 5d86f40..0000000 --- a/lacme.md +++ /dev/null @@ -1,413 +0,0 @@ -% lacme(1) -% [Guilhem Moulin](mailto:guilhem@fripost.org) -% December 2015 - -Name -==== - -lacme - [ACME] client written with process isolation and minimal -privileges in mind - -Synopsis -======== - -`lacme` [`--config=FILENAME`] [`--socket=PATH`] [*OPTION* …] *COMMAND* [*ARGUMENT* …] - -Description -=========== - -`lacme` is a small [ACME] client written with process isolation and -minimal privileges in mind. It is divided into four components, each -with its own executable: - - 1. A [`lacme-accountd`(1)] process to manage the account key and issue - SHA-256 signatures needed for each [ACME] command. (This process - binds to a UNIX-domain socket to reply to signature requests from - the [ACME] client.) - One can use the UNIX-domain socket forwarding facility of OpenSSH - 6.7 and later to run [`lacme-accountd`(1)] and `lacme` on different - hosts. Alternatively, the [`lacme-accountd`(1)] process can be - spawned by the “master” `lacme` process below; in that case, the - two processes communicate through a socket pair. - - 2. A “master” `lacme` process, which runs as root and is the only - component with access to the private key material of the server - keys. It is used to fork the [ACME] client (and optionally the - [ACME] webserver) after dropping root privileges. - 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. - - 3. An actual [ACME] client (specified with the *command* option of the - [`[client]` section](#client-section) of the configuration file), - which builds [ACME] commands and dialogues with the remote [ACME] - server. - Since [ACME] commands need to be signed with the account key, the - “master” `lacme` process passes the [`lacme-accountd`(1)] - UNIX-domain socket to the [ACME] client: data signatures are - 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]` - 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 - answer challenges.) That webserver only processes `GET` and `HEAD` - requests under the `/.well-known/acme-challenge/` URI. - Moreover temporary [`iptables`(8)] rules can be automatically - installed to open the HTTP port. - -Commands -======== - -`lacme account` [`--tos-agreed`] [`--register`] [*CONTACT* …] - -: Register (if `--registered` is set) a [`lacme-accountd`(1)]-managed - account key. A list of *CONTACT* information (such as `maito:` - URIs) can be specified in order for the [ACME] server to contact the - client for issues related to this registration (such as - notifications about server-initiated revocations). `--tos-agreed` - indicates agreement with the [ACME] server's Terms of Service (and - might be required for registration). - - If the account key is already registered, update the contact info - with the given list of *CONTACT* information. - - Upon success, `lacme` prints the new or updated Account Object from - the [ACME] server. - -`lacme` [`--config-certs=`*FILE*] [`--min-days=`*INT*] `newOrder` [*SECTION* …] - -: Read the certificate configuration *FILE* (see the **[certificate - configuration file](#certificate-configuration-file)** section below - for the configuration options), and request new Certificate Issuance - for each of its sections (or the given list of *SECTION*s). - Command alias: `new-order`. - -`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. - Command alias: `revoke-cert`. - -Generic options -=============== - -`--config=`*filename* - -: Use *filename* as configuration file. 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 - [`[client]` section](#client-section) of the configuration file. - Moreover this option is ignored when the configuration file has an - [`[accountd]` section](#accountd-section); in that case `lacme` - spawns [`lacme-accountd`(1)], and the two processes communicate - through a socket pair. - -`-h`, `--help` - -: Display a brief help and exit. - -`-q`, `--quiet` - -: Be quiet. - -`--debug` - -: Turn on debug mode. - -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 -*/etc/lacme/lacme.conf*. -Valid options are: - -Default section ---------------- - -*config-certs* - -: For certificate issuances (`newOrder` command), specify the - 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). - - 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`. - - Default: `lacme-certs.conf lacme-certs.conf.d/`. - -`[client]` section ------------------- - -This section is used for configuring the [ACME] client (which takes care -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`. - -*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 - recommended). - Default: `nogroup`. - -*command* - -: Path to the [ACME] client executable. - Default: `/usr/lib/lacme/client`. - -*server* - -: Root URI of the [ACME] server. - Default: `https://acme-v02.api.letsencrypt.org/directory`. - -*timeout* - -: Timeout in seconds after which the client stops polling the [ACME] - server and considers the request failed. - Default: `10`. - -*SSL_verify* - -: Whether to verify the server certificate chain. - Default: `Yes`. - -*SSL_version* - -: Specify the version of the SSL protocol used to transmit data. - -*SSL_cipher_list* - -: Specify the cipher list for the connection, see [`ciphers`(1ssl)] - for more information. - -`[webserver]` section ---------------------- - -This section is used to configure how [ACME] challenge responses are -served during certificate issuance. - -*listen* - -: Comma- or space-separated list of addresses to listen on. Valid - addresses are of the form `IPV4:PORT`, `[IPV6]:PORT` (where the - `:PORT` suffix is optional and defaults to the HTTP port 80), or an - absolute path of a UNIX-domain socket (created with mode `0666`). - Default: `/run/lacme-www.socket`. - - **Note**: The default value is only suitable when an external HTTP - daemon is publicly reachable and passes all ACME challenge requests - to the webserver component through the UNIX-domain socket - `/run/lacme-www.socket` (for instance using the provided - `/etc/lacme/apache2.conf` or `/etc/lacme/nginx.conf` configuration - snippets for each virtual host requiring authorization). If there - is no HTTP daemon bound to port 80 one needs to set *listen* to - `[::]` (or `0.0.0.0 [::]` when dual IPv4/IPv6 stack is disabled or - unavailable), and possibly also set *iptables* to `Yes`. - -*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. - -*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`. - -*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 - recommended). - Default: `www-data`. - -*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.) - Default: `/usr/lib/lacme/webserver`. - -*iptables* - -: Whether to automatically install temporary [`iptables`(8)] rules to - open the `ADDRESS[:PORT]` specified with *listen*. The rules are - automatically removed once `lacme` exits. - Default: `No`. - -`[accountd]` section ---------------------- - -This section is used for configuring the [`lacme-accountd`(1)] process. -If the section (including its header) is absent or commented out, -`lacme` connects to an existing UNIX-domain socket bound by a running -[`lacme-accountd`(1)] process. - -*user* - -: The username to drop privileges to (setting both effective and real - uid). Preserve root privileges if the value is empty. - -*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. - -*command* - -: Path to the [`lacme-accountd`(1)] executable. - Default: `/usr/bin/lacme-accountd`. - -*config* - -: Path to the [`lacme-accountd`(1)] configuration file. - Default: `/etc/lacme/lacme-accountd.conf`. - -*privkey* - -: The (private) account key to use for signing requests. See - [`lacme-accountd`(1)] for details. - -*quiet* - -: Be quiet. Possible values: `Yes`/`No`. - -Certificate configuration file -============================== - -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: - -*certificate* - -: Where to store the issued certificate (in PEM format). - At least one of *certificate* or *certificate-chain* is required. - -*certificate-chain* - -: Where to store the issued certificate, concatenated with the content - of the file specified specified with the *CAfile* option (in PEM - format). - At least one of *certificate* or *certificate-chain* is required. - -*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: - - openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/srv.key - -*min-days* - -: For an existing certificate, the minimum number of days before its - expiration date the section is considered for re-issuance. - A negative value forces reissuance, while the number `0` limits - reissuance to expired certificates. - Default: the value of the CLI option `--min-days`, or `21` if there - is no such option. - -*CAfile* - -: Path to the issuer's certificate. This is used for - *certificate-chain* and to verify the validity of each issued - certificate. - Specifying an empty value skip certificate validation. - Default: `/usr/share/lacme/lets-encrypt-x3-cross-signed.pem`. - -*hash* - -: Message digest algorithm to sign the Certificate Signing Request - with. - -*keyUsage* - -: Comma-separated list of Key Usages, see [`x509v3_config`(5ssl)]. - -*subject* - -: Subject field of the Certificate Signing Request, in the form - `/type0=value0/type1=value1/type2=…`. This option 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. - -*chown* - -: An optional `username[:groupname]` to chown the issued *certificate* - and *certificate-chain* to. - -*chmod* - -: An optional octal mode to chmod the issued *certificate* and - *certificate-chain* to. - -*notify* - -: Command to pass the the system's command shell (`/bin/sh -c`) - after successful installation of the *certificate* and/or - *certificate-chain*. - -Examples -======== - - ~$ sudo lacme account --register --tos-agreed mailto:noreply@example.com - ~$ sudo lacme newOrder - ~$ sudo lacme revokeCert /path/to/server/certificate.pem - -See also -======== - -[`lacme-accountd`(1)] - -[ACME]: https://tools.ietf.org/html/rfc8555 -[`lacme-accountd`(1)]: lacme-accountd.1.html -[`iptables`(8)]: http://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 diff --git a/pandoc2man.jq b/pandoc2man.jq new file mode 100755 index 0000000..69802a5 --- /dev/null +++ b/pandoc2man.jq @@ -0,0 +1,28 @@ +#!/usr/bin/jq -f + +def fixheaders: + if .t == "Header" then + .c[2][] |= (if .t == "Str" then .c |= ascii_upcase else . end) + else + . + end; + +def fixlinks: + if type == "object" then + if .t == "Link" then + if .c[2][0][0:7] == "mailto:" then . else .c[1][] end + else + map_values(fixlinks) + end + else if type == "array" then + map(fixlinks) + else + . + end + end; + +{ + "pandoc-api-version" + , meta + , blocks: .blocks | map(fixheaders | fixlinks) +} -- cgit v1.2.3