diff options
| -rw-r--r-- | README | 32 | ||||
| -rwxr-xr-x | letsencrypt | 38 |
2 files changed, 34 insertions, 36 deletions
@@ -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 } |