Merge branch 'master' into debian

2 files changed, 34 insertions, 36 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.
diff --git a/letsencrypt b/letsencrypt
index cba4271..027afd4 100755
--- a/letsencrypt
+++ b/letsencrypt
@@ -46,48 +46,14 @@ usage() {
     local msg="${1:-}"
     if [ "$msg" ]; then
         echo "$NAME: $msg" >&2
-        echo "Try '$NAME --help' for more information." >&2
+        echo "Try '$NAME --help' or consult the manpage for more information." >&2
         exit 1
     fi
     cat <<- EOF
 		Usage: $NAME [OPTIONS] new-reg ACCOUNTKEY [EMAIL ..]
 		  or: $NAME [OPTIONS] new-cert ACCOUNTKEY --output=CERT {--csr=CSR | CSR Options }
 		  or: $NAME [OPTIONS] revoke-cert ACCOUNTKEY CERT [CERT ..]
-
-		ACCOUNTKEY is the private key file of the user's account.  Generic options are:
-		    --genkey[=ALGO[:BITS]]  For 'new-*' commands, generate key pairs (with mode 0600) if they don't
-		                            exist already. (Default: "RSA".)  RSA is the only algorithm curently supported.
-		    --runas=USERNAME        Username to run the ACME client as. (This user doesn't need access to
-		                            any private key material.)
-		    --help, -?              Display this help text and exit
-		    --quiet, -q             Be quiet
-		    --debug                 Turn on debug mode
-
-		$NAME new-reg ACCOUNTKEY [EMAIL ..]
-		  Register a new ACCOUNTKEY; an optional list of EMAIL addresses can be supplied as contact information.
-
-		$NAME new-cert ACCOUNTKEY --output=CERT --csr=FILE
-		$NAME new-cert ACCOUNTKEY --output=CERT --key=FILE [--hash=ALGO] [--subject=STRING] [--san=STRING] [--keyusage=STRING]
-		  Request a new Certificate Issuance.  The Certificate Signing Request can be supplied directly, or
-		  generated from the server key using options --hash, --subject, --san and --keyusage.
-
-		    --min-age=SECONDS Skip the issuance if the certificate specified by --output exists and its
-		                      expiration date is more than SECONDS ahead.
-		    --csr=FILE        Certificate Signing Request to send (alternatively, use --key to generate it)
-		    --key=FILE        Server private key (use --genkey to generate it)
-		    --hash=DGST       Message digest to sign the CSR with (in PEM format)
-		    --subject=STRING  Subject name, formatted as "/type0=value0/type1=value1/type2=..." (default: "/")
-		    --san=STRING      Comma-separated list of Subject Alternative Names formatted as "type:value"
-		    --keyusage=STRING Comma-separated list of Key Usages, see x509v3_config(5ssl)
-		                      (default: "digitalSignature,keyEncipherment,keyCertSign")
-		    --output=FILE     Where to store the issued (signed) X.509 certificate
-		    --chain[=FILE]    Store the server certificate along with its intermediate CA in FILE; if FILE is
-		                      empty or omitted, use the file specified with --output
-		    --notify=COMMAND  Command to run upon success.  (This option can be repeated.)
-
-		$NAME revoke-cert {ACCOUNTKEY|SVRKEY} FILE [FILE ..]
-		  Request that the given certificate(s) FILE(s) be revoked.  The first argument can be either the account
-		  key file or the server's private key.
+		Consult the manpage for more information.
 	EOF
     exit 0
 }