aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README32
-rwxr-xr-xletsencrypt38
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
}