aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: 5e17a8d7cb34bef3f46d55e9cf61ff21a0c49c5e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
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:

  * A 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 this process on a different host.

  * A "master" 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,
    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.

  * An actual ACME client, which builds ACME commands and dialogues with
    the remote ACME server.  Since ACME commands need to be signed with
    the account key, the "master" process passes the UNIX-domain socket
    of the account key manager to the ACME client: data signatures are
    requested by writing the data to be signed to the socket.

  * For certificate issuances, an optional webserver which is spawned by
    the "master".  (The only challenge type currently supported 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.

Consult the manuals for more information.

    https://guilhem.org/man/lacme.1.html
    https://guilhem.org/man/lacme-accountd.1.html

_______________________________________________________________________

Requesting new Certificate Issuance with the ACME protocol generally
works as follows:

  1. Generate a Certificate Signing Request.  This requires access to
     the private part of the server key.
  2. Issue an issuance request against the ACME server.
  3. Answer the ACME Identifier Validation Challenges.  The challenge
     type "http-01" requires a webserver to listen on port 80 for each
     address for which an authorization request is issued; if there is
     no running webserver, root privileges are required to bind against
     port 80 and to install firewall rules to temporarily open the port.
  4. Install the certificate (after verification) and restart the
     service.  This usually requires root access as well.

Steps 1,3,4 need to be run on the host for which an authorization
request is issued.  However the the issuance itself (step 2) could be
done from another machine.  Furthermore, each ACME command (step 2), as
well as the key authorization token in step 3, need to be signed using
an account key.  The account key can be stored on another machine, or
even on a smartcard.

_______________________________________________________________________

lacme is Copyright© 2016 Guilhem Moulin ⟨guilhem@fripost.org⟩, and
licensed for use under the GNU General Public License version 3 or
later.  See ‘COPYING’ for specific terms and distribution information.