Refactoring to use the account key manager.

1 files changed, 294 insertions, 119 deletions

diff --git a/letsencrypt.1 b/letsencrypt.1
index a16e165..2175bd2 100644
--- a/letsencrypt.1
+++ b/letsencrypt.1
@@ -1,187 +1,362 @@
-.TH LETSENCRYPT "1" "DECEMBER 2015" "Tiny Let's Encrypt ACME client" "User Commands"
+.TH LETSENCRYPT "1" "MARCH 2016" "Tiny Let's Encrypt ACME client" "User Commands"
 
 .SH NAME
 letsencrypt \- Tiny Let's Encrypt ACME client
 
 .SH SYNOPSIS
-.B letsencrypt\fR [\fIOPTION\fR ...] \fICOMMAND\fR \fIACCOUNTKEY\fR [\fIARGUMENT\fR ...]
+.B letsencrypt\fR [\fB\-\-config=\fIFILENAME\fR]
+[\fB\-\-socket=\fIPATH\fR] [\fIOPTION\fR ...] \fICOMMAND\fR
+[\fIARGUMENT\fR ...]
 
 
 .SH DESCRIPTION
 .PP
 .B letsencrypt\fR is a tiny ACME client written with process isolation
 and minimal privileges in mind.
-It is divided into three components:
-
-.nr step 1 1
-.IP \n[step]. 8
-The \(lqmaster\(rq 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 (\fBnew-cert\fR 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 \fB--notify\fR.
-
-.IP \n[step]. 8
-The actual ACME client, which runs as the user specified with
-\fB--runas\fR (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.
-
-.IP \n+[step].
-An optional webserver, which is spawned by the master process (when
-nothing is listening on localhost:80); \fBsocat\fR(1) is used to listen
-on port 80 and to change the user (owner) and group of the process to
-\(lqwww-data:www-data\(rq.
+It is divided into four components, each with its own executable:
+
+.IP \[bu] 4
+A \fIletsencrypt\-accountd\fR(1) process to manage the account key and
+issue SHA\-256 signatures needed for each ACME command.
+(This process binds to a UNIX\-domain socket to reply to signature
+requests from the ACME client.)
+One can use the UNIX\-domain socket forwarding facility of OpenSSH 6.7
+and later to run \fIletsencrypt\-accountd\fR(1) and \fBletsencrypt\fR on
+different hosts.
+
+.IP \[bu] 4
+A \(lqmaster\(rq \fBletsencrypt\fR process, which runs as root and is
+the only component with access to the private key material of the server
+keys.
+It is used to fork the ACME client (and optionally the ACME webserver)
+after dropping root privileges.
+For certificate issuances (\fBnew\-cert\fR command), it also generates
+Certificate Signing Requests, then verifies the validity of the issued
+certificate, and optionally reloads or restarts services when the
+\fInotify\fR option is set.
+
+.IP \[bu] 4
+An actual ACME client (specified with the \fIcommand\fR option of the
+\(lq[client]\(rq section of the configuration file), which builds ACME
+commands and dialogues with the remote ACME server.
+Since ACME commands need to be signed with the account key, the
+\(lqmaster\(rq \fBletsencrypt\fR process passes the
+\fIletsencrypt\-accountd\fR(1) UNIX\-domain socket to the ACME client:
+data signatures are requested by writing the data to be signed to the
+socket.
+
+.IP \[bu] 4
+For certificate issuances (\fBnew\-cert\fR command), an optional
+webserver (specified with the \fIcommand\fR option of the
+\(lq[webserver]\(rq section of the configuration file), which is spawned
+by the \(lqmaster\(rq \fBletsencrypt\fR process when no service is
+listening on the HTTP port.
 (The only challenge type currently supported by \fBletsencrypt\fR is
-\(lqhttp-01\(rq, 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
-\(lq/.well-known/acme-challenge\(rq 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 \(lq/var/www/acme-challenge\(rq
-root directory, which must not exist.
+\(lqhttp\-01\(rq, which requires a webserver to answer challenges.)
+That webserver only processes GET and HEAD requests under the
+\(lq/.well\-known/acme\-challenge/\(rq URI.
+By default some \fIiptables\fR(1) rules are automatically installed to
+open the HTTP port, and removed afterwards.
+
+.SH COMMANDS
+.TP
+.B letsencrypt \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBnew\-reg \fR[\fICONTACT\fR ...]
+Register the account key managed by \fIletsencrypt\-accountd\fR(1).  A
+list of \fICONTACT\fR information (such as \(lqmaito:\(rq
+URIs) can be specified in order for the server to contact the client for
+issues related to this registration (such as notifications about
+server\-initiated revocations).
+
+\fB\-\-agreement\-uri=\fR can be used to specify a \fIURI\fR referring
+to a subscriber agreement or terms of service provided by the server;
+adding this options indicates the client's agreement with the referenced
+terms.  Note that the server might require the client to agree to
+subscriber agreement before performing any further actions.
+
+If the account key is already registered, \fBletsencrypt\fR prints the
+URI of the existing registration and aborts.
+
+.TP
+.B letsencrypt \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBreg=\fIURI\fR \fR[\fICONTACT\fR ...]
+
+Dump or edit the registration \fIURI\fR (relative to the ACME server URI,
+which is specified with the \fIserver\fR option of the \(lq[client]\(rq
+section of the configuration file).
+
+When specified, the list of \fICONTACT\fR information and the agreement
+\fIURI\fR are sent to the server to replace the existing values.
+
+.TP
+.B letsencrypt \fR[\fB\-\-config\-certs=\fIFILE\fR]\fB \fBnew\-cert \fR[\fISECTION\fR ...]
+
+Read the certificate configuration \fIFILE\fR (see the \fBCERTIFICATE
+CONFIGURATION FILE\fR section below for the configuration options), and
+request new Certificate Issuance for each of its sections (or the given
+list of \fISECTION\fRs).
+
+.TP
+.B letsencrypt \fBrevoke\-cert \fIFILE\fR [\fIFILE\fR ...]
+
+Request that the given certificate(s) \fIFILE\fR(s) be revoked.  For
+this command, \fIletsencrypt\-accountd\fR(1) can be pointed to either
+the account key or the server's private key.
+
 
 .SH GENERIC OPTIONS
 .TP
-.B \-\-runas=\fIusername\fR
-Username to run the ACME client as.  This user does not need access to
-any private key material.  The ACME client runs as root when this option
-is omited (not recommended).
+.B \-\-config=\fIfilename\fR
+Use \fIfilename\fR as configuration file.  See the \fBCONFIGURATION
+FILE\fR section below for the configuration options.
 
 .TP
-.B \-?\fR, \fB\-\-help\fR
-Display a brief help and exit.
+.B \-\-socket=\fIpath\fR
+Use \fIpath\fR as the \fIletsencrypt\-accountd\fR(1) UNIX\-domain socket
+to connect to for signature requests from the ACME client.
+\fBletsencrypt\fR aborts if \fIpath\fR is readable or writable by
+other users, or if its parent directory is writable by other users.
+This overrides the \fIsocket\fR option of the \(lq[client]\(rq section
+of the configuration file.
 
 .TP
-.B \-q\fR, \fB\-\-quiet\fR
-Try to be quiet.
+.B \-?\fR, \fB\-\-help\fR
+Display a brief help and exit.
 
 .TP
 .B \-\-debug
 Turn on debug mode.
 
 
-.SH ACCOUNT KEY REGISTRATION
-.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-reg\fR \fIACCOUNTKEY\fR [\fIEMAIL\fR ...]
+.SH CONFIGURATION FILE
+If \fB\-\-config=\fR is not given, \fBletsencrypt\fR uses the first
+existing configuration file among
+\fI./letsencrypt.conf\fR,
+\fI$XDG_CONFIG_HOME/letsencrypt\-tiny/letsencrypt.conf\fR (or
+\fI~/.config/letsencrypt\-tiny/letsencrypt.conf\fR if the
+XDG_CONFIG_HOME environment variable is not set), and
+\fI/etc/letsencrypt\-tiny/letsencrypt.conf\fR.
+Valid options are:
 
-Registers the given \fIACCOUNTKEY\fR.  An optional list of \fIEMAIL\fR
-addresses can be given as contact information.
+.TP
+Default section
+.RS
+.TP
+.I config\-certs
+For certificate issuances (\fBnew\-cert\fR command), specify the
+certificate configuration file to use (see the \fBCERTIFICATE
+CONFIGURATION FILE\fR section below for the configuration options).
+.RE
 
 .TP
-.B \-\-genkey\fR[\fB=\fIALGO\fR[:\fIBITS\fR]]
-Automatically generate the \fIACCOUNTKEY\fR (with mode 0600) if it does
-not exist, using a \fIBITS\fR\-long \fIALGO\fR key.
-The \fBopenssl\fR(1) default length is used when \fIBITS\fR is omited.
-The default \fIALGO\fRrithm is \(lqRSA\(rq, which is also the only one
-currently supported.
+\(lq[client]\(rq section
+This section is used for configuring the ACME client (which takes care
+of ACME commands and dialogues with the remote ACME server).
 
+.RS
+.TP
+.I socket
+See \fB\-\-socket=\fR.
+Default: \(lq$XDG_RUNTIME_DIR/S.letsencrypt\(rq if the XDG_RUNTIME_DIR
+environment variable is set.
 
-.SH CERTIFICATE ISSUANCE
-.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-cert\fR \fIACCOUNTKEY\fR
-\fB\-\-output=\fICERT\fR \fB\-\-csr=\fIFILE\fR
+.TP
+.I user
+The username to drop privileges to (setting both effective and real
+uid).
+Preserve root privileges if the value is empty (not recommended).
+Default: \(lqnobody\(rq.
 
-.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-cert\fR \fIACCOUNTKEY\fR
-\fB\-\-output=\fICERT\fR \fB\-\-key=\fIFILE\fR [\fB\-\-hash=\fIALGO\fR]
-[\fB\-\-subject=\fISTRING\fR] [\fB\-\-san=\fISTRING\fR]
-[\fB\-\-keyusage=\fISTRING\fR]
+.TP
+.I group
+The groupname to drop privileges to (setting both effective and real
+gid, and also setting the list of supplementary gids to that single
+group).  Preserve root privileges if the value is empty (not
+recommended).
+Default: \(lqnogroup\(rq.
 
-Request a new Certificate Issuance using the given \fIACCOUNTKEY\fR.
-The Certificate Signing Request can be supplied directly using
-\fB\-\-csr\fR, or generated from the server key (\fB\-\-key\fR) using
-options \fB\-\-hash\fR, \fB\-\-subject\fR, \fB\-\-san\fR and \fB\-\-keyusage\fR.
+.TP
+.I command
+Path to the ACME client executable.
+Default: \(lq/usr/lib/letsencrypt\-tiny/client\(rq.
 
-The issued X.509 certificate is then validated, and upon success is
-placed (in PEM format) into the file specified with \fB\-\-output\fR; the
-optional \fB\-\-chain\fR option can be used to append the issuer
-certificate as well.
+.TP
+.I server
+Root URI of the ACME server.
+Default: \(lqhttps://acme\-v01.api.letsencrypt.org/\(rq.
 
 .TP
-.B \-\-min-age=\fISECONDS
-Skip the issuance if the certificate specified by \fB\-\-output\fR exists
-and its expiration date is more than \fISECONDS\fR ahead.
+.I timeout
+Timeout in seconds after which the client stops polling the ACME server
+and considers the request failed.
+Default: \(lq10\(rq.
 
 .TP
-.B \-\-csr=\fIFILE
-Certificate Signing Request to send (alternatively, use \fB\-\-key\fR to
-generate it from the private server key).
+.I SSL_verify
+Whether to verify the server certificate chain.
+Default: \(lqYes\(rq.
 
 .TP
-.B \-\-key=\fIFILE
-Server private key used to generate the Certificate Signing Request when
-\fB\-\-csr\fR is omitted.  (Use \fB\-\-genkey\fR to generate it
-automatically.)
+.I SSL_version
+Specify the version of the SSL protocol used to transmit data.
 
 .TP
-.B \-\-genkey\fR[\fB=\fIALGO\fR[:\fIBITS\fR]]
-Automatically generate the server private key (with mode 0600) if it
-does not exist, using a \fIBITS\fR\-long \fIALGO\fR key.
-The \fBopenssl\fR(1) default length is used when \fIBITS\fR is omited.
-The default \fIALGO\fRrithm is \(lqRSA\(rq, which is also the only one
-currently supported.
+.I SSL_cipher_list
+Specify the cipher list for the connection.
+.RE
 
 .TP
-.B \-\-hash=\fIDGST
-Message digest to sign the Certificate Signing Request with.
+\(lq[webserver]\(rq section
+This section is used for configuring the ACME webserver.
 
+.RS
 .TP
-.B \-\-subject=\fR/\fItype0\fR=\fIvalue0\fR/\fItype1\fR=\fIvalue1\fR/\fItype2\fR=...
-Subject name to use in the Certificate Signing Request.
+.I listen
+Specify the local address to listen on, in the form
+\fIADDRESS\fR[:\fIPORT\fR].
+If \fIADDRESS\fR is enclosed with brackets \(oq[\(cq/\(oq]\(cq then it
+denotes an IPv6; an empty \fIADDRESS\fR means \(oq0.0.0.0\(cq.
+Default: \(lq:80\(rq.
 
 .TP
-.B \-\-san=\fItype0\fR:\fIvalue1\fR,\fItype1\fR:\fIvalue1\fR,\fItype2\fR:...
-Comma-separated list of Subject Alternative Names.  The only \fItype\fR
-currently supported is \(lqDNS\(rq, to specify an alternative domain
-name.
+.I challenge\-directory
+If a webserver is already running, specify a non\-existent directory
+under which the webserver is configured to serve GET requests for
+challenge files under \(lq/.well\-known/acme\-challenge/\(rq (for each
+virtual hosts requiring authorization) as static files.
+Default: \(lq/var/www/acme\-challenge\(rq.
 
 .TP
-.B \-\-keyusage=\fISTRING
-Comma-separated list of Key Usages, see x509v3_config(5ssl).
-(Default: \(lqdigitalSignature,keyEncipherment,keyCertSign\(rq.)
+.I user
+The username to drop privileges to (setting both effective and real
+uid).
+Preserve root privileges if the value is empty (not recommended).
+Default: \(lqwww\-data\(rq.
 
 .TP
-.B \-\-output=\fIFILE
-Where to copy the issued (signed) X.509 certificate.
+.I group
+The groupname to drop privileges to (setting both effective and real
+gid, and also setting the list of supplementary gids to that single
+group).  Preserve root privileges if the value is empty (not
+recommended).
+Default: \(lqwww\-data\(rq.
 
 .TP
-.B \-\-chain=\fR[\fIFILE\fR]
-Store the server certificate along with its intermediate CA in
-\fIFILE\fR.  If \fIFILE\fR is empty or omitted, use the file specified
-with \fB\-\-output\fR instead.
+.I command
+Path to the ACME webserver executable.
+Default: \(lq/usr/lib/letsencrypt\-tiny/webserver\(rq.
 
 .TP
-.B \-\-notify=\fICOMMAND\fR
-Command to run upon success.  (This option can be repeated to run
-multiple commands.)
+.I iptables
+Whether to automatically install \fIiptables\fR(1) rules to open the
+\fIADDRESS\fR[:\fIPORT\fR] specified with \fIlisten\fR.
+Theses rules are automatically removed once \fBletsencrypt\fR exits.
+Default: \(lqYes\(rq.
+.RE
+
+
+.SH CERTIFICATE CONFIGURATION FILE
+For certificate issuances (\fBnew\-cert\fR command), a separate file is
+used to configure paths to the certificate and key, as well as the
+subject, subjectAltName, etc. to generate Certificate Signing Requests.
+If \fB\-\-config\-certs=\fR is not given, and if the
+\fIconfig\-certs\fR configuration option is absent,
+then \fBletsencrypt\fR uses the first existing configuration file among
+\fI./letsencrypt\-certs.conf\fR,
+\fI$XDG_CONFIG_HOME/letsencrypt\-tiny/letsencrypt\-certs.conf\fR (or
+\fI~/.config/letsencrypt\-tiny/letsencrypt\-certs.conf\fR if the
+XDG_CONFIG_HOME environment variable is not set), and
+\fI/etc/letsencrypt\-tiny/letsencrypt\-certs.conf\fR.
+Each section denotes a separate certificate issuance.
+Valid options are:
 
+.TP
+.I certificate
+Where to store the issued certificate (in PEM format).
+At least one of \fIcertificate\fR or \fIcertificate\-chain\fR is
+required.
+
+.TP
+.I certificate\-chain
+Where to store the issued certificate, concatenated with the content of
+the file specified specified with the \fICAfile\fR option (in PEM
+format).
+At least one of \fIcertificate\fR or \fIcertificate\-chain\fR is
+required.
 
-.SH CERTIFICATE REVOKATION
-.B letsencrypt\fR [\fIOPTION\fR ...] \fBrevoke\-cert\fR {\fIACCOUNTKEY\fR|\fISVRKEY\fR} \fIFILE\fR [\fIFILE\fR ...]
+.TP
+.I certificate\-key
+Path the service's private key.  This option is required.  The following
+command can be used to generate a new 4096\-bits RSA key in PEM format
+with mode 0600:
 
-Request that the given certificate(s) \fIFILE\fR(s) be revoked.  The
-first argument after the command name can be either the account key file
-or the private part of the certificate(s) to revoke.
+.nf
+    openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/priv.key
+.fi
 
+.TP
+.I min\-days
+For an existing certificate, the minimum number of days before its
+expiration date the section is considered for re\-issuance.
+Default: \(lq10\(rq.
 
-.SH EXAMPLES
 
 .TP
-letsencrypt \-\-runas=letsencrypt new\-reg \-\-genkey=RSA:4096 /etc/ssl/letsencrypt.key admin@fripost.org
-Register a new account key \(lq/etc/ssl/letsencrypt.key\(rq using
-\(lqadmin@fripost.org\(rq as contact information.  A 4096-bits long RSA
-key is generated (with mode 0600) if the key file does not exists.
+.I CAfile
+Path to the issuer's certificate.  This is used for
+\fIcertificate\-chain\fR and to verify the validity of each issued
+certificate.
+Specifying an empty value skip certificate validation.
+Default: \(lq/usr/share/letsencrypt\-tiny/lets\-encrypt\-x1\-cross\-signed.pem\(rq.
+
+.TP
+.I hash
+Message digest to sign the Certificate Signing Request with.
+
+.TP
+.I keyUsage
+Comma\-separated list of Key Usages, see \fIx509v3_config\fR(5ssl).
+
+.TP
+.I subject
+Subject field of the Certificate Signing Request, in the form
+\fR/\fItype0\fR=\fIvalue0\fR/\fItype1\fR=\fIvalue1\fR/\fItype2\fR=...
+This option is required.
+
+.TP
+.I subjectAltName
+Comma\-separated list of Subject Alternative Names, in the form
+\fItype0\fR:\fIvalue1\fR,\fItype1\fR:\fIvalue1\fR,\fItype2\fR:...
+The only \fItype\fR currently supported is \(lqDNS\(rq, to specify an
+alternative domain name.
+
+.TP
+.I chown
+An optional \fIusername\fR[:\fIgroupname\fR] to chown the issued
+\fIcertificate\fR and \fIcertificate\-chain\fR with.
+
+.TP
+.I chmod
+An optional octal mode to chmod the issued \fIcertificate\fR and
+\fIcertificate\-chain\fR with.
 
 .TP
-letsencrypt \-\-runas=letsencrypt new\-cert /etc/ssl/letsencrypt.key \-\-output=/etc/nginx/ssl/www.fripost.org.pem \-\-chain \-\-key=/etc/nginx/ssl/www.fripost.org.key \-\-hash=SHA512 \-\-subject=/O=Fripost/CN=fripost.org \-\-san=DNS:fripost.org,DNS:www.fripost.org,DNS:wiki.fripost.org \-\-min-age=432000 \-\-notify='systemctl restart nginx'
-Request issuance of a new (chained) certificate, but only if it doesn't exist or expires in less than 5 days; restart nginx upon success.
+.I notify
+Command to pass the the system's command shell (\(lq/bin/sh \-c\(rq)
+after successful installation of the \fIcertificate\fR and/or
+\fIcertificate\-chain\fR.
+
+
+.SH EXAMPLES
+
+.nf
+    ~$ sudo letsencrypt new-reg mailto:noreply@example.com
+    ~$ sudo letsencrypt reg=/acme/reg/137760 --agreement-uri=https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf
+    ~$ sudo letsencrypt new-cert
+    ~$ sudo letsencrypt revoke-cert /path/to/server/certificate.pem
+.fi
+
 
+.SH SEE ALSO
+\fBletsencrypt\-accountd\fR(1)
 
 .SH AUTHOR
 Written by Guilhem Moulin