aboutsummaryrefslogtreecommitdiffstats
path: root/lacme.md
diff options
context:
space:
mode:
Diffstat (limited to 'lacme.md')
-rw-r--r--lacme.md355
1 files changed, 355 insertions, 0 deletions
diff --git a/lacme.md b/lacme.md
new file mode 100644
index 0000000..a16f23d
--- /dev/null
+++ b/lacme.md
@@ -0,0 +1,355 @@
+% lacme(1)
+% [Guilhem Moulin](mailto:guilhem@fripost.org)
+% December 2015
+
+Name
+====
+
+lacme - [ACME] client
+
+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.
+
+ 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 (`new-cert` 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 (`new-cert` 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` process when no service is listening
+ on the HTTP port. (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.
+ By default some [`iptables`(8)] rules are automatically installed to
+ open the HTTP port, and removed afterwards.
+
+Commands
+========
+
+`lacme` [`--agreement-uri=`*URI*] `new-reg` [*CONTACT* …]
+
+: Register the account key managed by [`lacme-accountd`(1)]. A list
+ of *CONTACT* information (such as `maito:` URIs) can be specified in
+ order for the server to contact the client for issues related to
+ this registration (such as notifications about server-initiated
+ revocations).
+
+ `--agreement-uri=` can be used to specify a *URI* referring to a
+ subscriber agreement or terms of service provided by the server;
+ adding this options indicates the client's agreement with the
+ referenced terms. Note that the server might require the client to
+ agree to subscriber agreement before performing any further actions.
+
+ If the account key is already registered, `lacme` prints the URI of
+ the existing registration and aborts.
+
+`lacme` [`--agreement-uri=`*URI*] `reg=`*URI* [*CONTACT* …]
+
+: Dump or edit the registration *URI* (relative to the [ACME] server
+ URI, which is specified with the *server* option of the [`[client]`
+ section](#client-section) of the configuration file).
+
+ When specified, the list of *CONTACT* information and the agreement
+ *URI* are sent to the server to replace the existing values.
+
+`lacme` [`--config-certs=`*FILE*] `new-cert` [*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).
+
+`lacme` `revoke-cert` *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.
+
+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 overrides the
+ *socket* option of the [`[client]` section](#client-section) of the
+ configuration file.
+
+`-?`, `--help`
+
+: Display a brief help and exit.
+
+`--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 (`new-cert` command), specify the
+ certificate configuration file to use (see the **[certificate
+ configuration file](#certificate-configuration-file)** section below
+ for the configuration options).
+
+`[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-v01.api.letsencrypt.org/`.
+
+*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 for configuring the [ACME] webserver.
+
+*listen*
+
+: Specify the local address to listen on, in the form
+ `ADDRESS[:PORT]`. If `ADDRESS` is enclosed with brackets ‘[’/‘]’
+ then it denotes an IPv6; an empty `ADDRESS` means `0.0.0.0`.
+ Default: `:80`.
+
+*challenge-directory*
+
+: If a webserver is already running, specify a non-existent directory
+ under which the webserver is configured to serve `GET` requests for
+ challenge files under `/.well-known/acme-challenge/` (for each
+ virtual hosts requiring authorization) as static files.
+ Default: `/var/www/acme-challenge`.
+
+*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.
+ Default: `/usr/lib/lacme/webserver`.
+
+*iptables*
+
+: Whether to automatically install [`iptables`(8)] rules to open the
+ `ADDRESS[:PORT]` specified with *listen*. Theses rules are
+ automatically removed once `lacme` exits.
+ Default: `Yes`.
+
+Certificate configuration file
+==============================
+
+For certificate issuances (`new-cert` 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.
+If `--config-certs=` is not given, and if the `config-certs`
+configuration option is absent, then `lacme` uses the first existing
+configuration file among *./lacme-certs.conf*,
+*$XDG_CONFIG_HOME/lacme/lacme-certs.conf* (or
+*~/.config/lacme/lacme-certs.conf* if the `XDG_CONFIG_HOME` environment
+variable is not set), and */etc/lacme/lacme-certs.conf*.
+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/priv.key
+
+*min-days*
+
+: For an existing certificate, the minimum number of days before its
+ expiration date the section is considered for re-issuance.
+ Default: `10`.
+
+*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* with.
+
+*chmod*
+
+: An optional octal mode to chmod the issued *certificate* and
+ *certificate-chain* with.
+
+*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 new-reg mailto:noreply@example.com
+ ~$ sudo lacme reg=/acme/reg/137760 --agreement-uri=https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf
+ ~$ sudo lacme new-cert
+ ~$ sudo lacme revoke-cert /path/to/server/certificate.pem
+
+
+See also
+========
+
+[`lacme-accountd`(1)]
+
+[ACME]: https://tools.ietf.org/html/draft-ietf-acme-acme-02
+[`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