Merge branch 'master' into debian

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.