Makefile: Major refactoring, add install and uninstall targets.

Honor BUILD_DOCDIR and DESTDIR variables.

1 files changed, 413 insertions, 0 deletions

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