Add README.

1 files changed, 32 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..4de2a20
--- /dev/null
+++ b/README
@@ -0,0 +1,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.