aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README85
1 files changed, 54 insertions, 31 deletions
diff --git a/README b/README
index 4de2a20..69a1859 100644
--- a/README
+++ b/README
@@ -1,32 +1,55 @@
+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.
+
+_______________________________________________________________________
+
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.
+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" process when no service is listening on the HTTP
+ port. (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. By default some iptables(1)
+ rules are automatically installed to open the HTTP port, and removed
+ afterwards.