diff options
Diffstat (limited to 'lacme.8.md')
| -rw-r--r-- | lacme.8.md | 413 |
1 files changed, 413 insertions, 0 deletions
diff --git a/lacme.8.md b/lacme.8.md new file mode 100644 index 0000000..79fb300 --- /dev/null +++ b/lacme.8.md @@ -0,0 +1,413 @@ +% lacme(8) +% [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 |