| 1 |
lacme is a small ACME client written with process isolation and minimal |
| 2 |
privileges in mind. It is divided into four components, each with its |
| 3 |
own executable: |
| 4 |
|
| 5 |
* A process to manage the account key and issue SHA-256 signatures |
| 6 |
needed for each ACME command. (This process binds to a UNIX-domain |
| 7 |
socket to reply to signature requests from the ACME client.) One |
| 8 |
can use the UNIX-domain socket forwarding facility of OpenSSH 6.7 |
| 9 |
and later to run this process on a different host. |
| 10 |
|
| 11 |
* A "master" process, which runs as root and is the only component |
| 12 |
with access to the private key material of the server keys. It is |
| 13 |
used to fork the ACME client (and optionally the ACME webserver) |
| 14 |
after dropping root privileges. For certificate issuances, |
| 15 |
it also generates Certificate Signing Requests, then verifies the |
| 16 |
validity of the issued certificate, and optionally reloads or |
| 17 |
restarts services when the notify option is set. |
| 18 |
|
| 19 |
* An actual ACME client, which builds ACME commands and dialogues with |
| 20 |
the remote ACME server. Since ACME commands need to be signed with |
| 21 |
the account key, the "master" process passes the UNIX-domain socket |
| 22 |
of the account key manager to the ACME client: data signatures are |
| 23 |
requested by writing the data to be signed to the socket. |
| 24 |
|
| 25 |
* For certificate issuances, an optional webserver which is spawned by |
| 26 |
the "master". (The only challenge type currently supported is |
| 27 |
"http-01", which requires a webserver to answer challenges.) That |
| 28 |
webserver only processes GET and HEAD requests under the |
| 29 |
"/.well-known/acme-challenge/" URI. Moreover temporary iptables(8) |
| 30 |
rules can be automatically installed to open the HTTP port. |
| 31 |
|
| 32 |
Consult the manuals for more information. |
| 33 |
|
| 34 |
https://guilhem.org/man/lacme.8.html |
| 35 |
https://guilhem.org/man/lacme-accountd.1.html |
| 36 |
|
| 37 |
_______________________________________________________________________ |
| 38 |
|
| 39 |
Requesting new Certificate Issuance with the ACME protocol generally |
| 40 |
works as follows: |
| 41 |
|
| 42 |
1. Generate a Certificate Signing Request. This requires access to |
| 43 |
the private part of the server key. |
| 44 |
2. Issue an issuance request against the ACME server. |
| 45 |
3. Answer the ACME Identifier Validation Challenges. The challenge |
| 46 |
type "http-01" requires a webserver to listen on port 80 for each |
| 47 |
address for which an authorization request is issued; if there is |
| 48 |
no running webserver, root privileges are required to bind against |
| 49 |
port 80 and to install firewall rules to temporarily open the port. |
| 50 |
4. Install the certificate (after verification) and restart the |
| 51 |
service. This usually requires root access as well. |
| 52 |
|
| 53 |
Steps 1,3,4 need to be run on the host for which an authorization |
| 54 |
request is issued. However the the issuance itself (step 2) could be |
| 55 |
done from another machine. Furthermore, each ACME command (step 2), as |
| 56 |
well as the key authorization token in step 3, need to be signed using |
| 57 |
an account key. The account key can be stored on another machine, or |
| 58 |
even on a smartcard. |
| 59 |
|
| 60 |
_______________________________________________________________________ |
| 61 |
|
| 62 |
lacme is Copyright © 2015-2021 Guilhem Moulin ⟨[email protected]⟩, and |
| 63 |
licensed for use under the GNU General Public License version 3 or |
| 64 |
later. See ‘COPYING’ for specific terms and distribution information. |