aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: 4de2a209b60b182ae0cee65b363bc6eded10e53e (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
letsencrypt is a tiny ACME client written with process isolation and
minimal privileges in mind.  It is divided into three components:

1. The "master" process, which runs as root and is the only component
   with access to the private key material (both account and server
   keys).  It is only used to fork the other components (after dropping
   privileges), and to sign ACME requests (JSON Web Signatures); for
   certificate issuance ("new-cert" command), it is also used to
   generate the Certificate Signing Request, then to verify the validity
   of the issued certificate, and optionally to reload or restart
   services using "--notify".

2. The actual ACME client, which runs as the user specified with
   "--runas" (or root if the option is omitted).  It builds ACME
   requests and dialogues with the remote ACME server.  All requests
   need to be signed with the account key, but this process doesn't need
   direct access to any private key material: instead, it write the data
   to be signed to a pipe shared with the master process, which in turns
   replies with its SHA-256 signature.

3. An optional webserver, which is spawned by the master process (when
   nothing is listening on localhost:80); socat(1) is used to listen on
   port 80 and to change the user (owner) and group of the process to
   "www-data:www-data".  (The only challenge type currently supported by
   letsencrypt-tiny is "http-01", hence a webserver is required.) Some
   iptables rules are automatically added to open port 80, and removed
   afterwards.  The web server only processes GET requests under the
   "/.well-known/acme-challenge" URI.
   If a webserver is already listening on port 80, it needs to be
   configured to serve these URIs (for each virtual-hosts requiring
   authorization) as static files under the
   "/var/www/acme-challenge" root directory, which must not exist.