diff options
authorGuilhem Moulin <guilhem@fripost.org>2015-12-18 01:59:34 +0100
committerGuilhem Moulin <guilhem@fripost.org>2015-12-18 01:59:34 +0100
commit0f654cd4573dc437fc46c8fa30f731f5a6589fd6 (patch)
parent9b4e37696a8ae05650a2aec57ba294fc4785ae0d (diff)
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.