Rename ‘letsencrypt-tiny’ to ‘lacme’.

1 files changed, 364 insertions, 0 deletions

diff --git a/lacme.1 b/lacme.1
new file mode 100644
index 0000000..bfe4f45
--- /dev/null
+++ b/lacme.1
@@ -0,0 +1,364 @@
+.TH LACME "1" "MARCH 2016" "ACME client" "User Commands"
+
+.SH NAME
+lacme \- ACME client
+
+.SH SYNOPSIS
+.B lacme\fR [\fB\-\-config=\fIFILENAME\fR] [\fB\-\-socket=\fIPATH\fR]
+[\fIOPTION\fR ...] \fICOMMAND\fR [\fIARGUMENT\fR ...]
+
+
+.SH DESCRIPTION
+.PP
+.B lacme\fR is a tiny ACME client written with process isolation and
+minimal privileges in mind.
+It is divided into four components, each with its own executable:
+
+.IP \[bu] 4
+A \fIlacme\-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 \fIlacme\-accountd\fR(1) and \fBlacme\fR on different
+hosts.
+
+.IP \[bu] 4
+A \(lqmaster\(rq \fBlacme\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 \fBlacme\fR process passes the \fIlacme\-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 \fBlacme\fR process when no service is listening
+on the HTTP port.
+(The only challenge type currently supported by \fBlacme\fR is
+\(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 lacme \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBnew\-reg
+\fR[\fICONTACT\fR ...] Register the account key managed by
+\fIlacme\-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, \fBlacme\fR prints the URI of
+the existing registration and aborts.
+
+.TP
+.B lacme \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 lacme \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 lacme \fBrevoke\-cert \fIFILE\fR [\fIFILE\fR ...]
+
+Request that the given certificate(s) \fIFILE\fR(s) be revoked.  For
+this command, \fIlacme\-accountd\fR(1) can be pointed to either the
+account key or the server's private key.
+
+
+.SH GENERIC OPTIONS
+.TP
+.B \-\-config=\fIfilename\fR
+Use \fIfilename\fR as configuration file.  See the \fBCONFIGURATION
+FILE\fR section below for the configuration options.
+
+.TP
+.B \-\-socket=\fIpath\fR
+Use \fIpath\fR as the \fIlacme\-accountd\fR(1) UNIX\-domain socket to
+connect to for signature requests from the ACME client.  \fBlacme\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 \-?\fR, \fB\-\-help\fR
+Display a brief help and exit.
+
+.TP
+.B \-\-debug
+Turn on debug mode.
+
+
+.SH CONFIGURATION FILE
+If \fB\-\-config=\fR is not given, \fBlacme\fR uses the first existing
+configuration file among \fI./lacme.conf\fR,
+\fI$XDG_CONFIG_HOME/lacme/lacme.conf\fR (or
+\fI~/.config/lacme/lacme.conf\fR if the XDG_CONFIG_HOME environment
+variable is not set), and \fI/etc/lacme/lacme.conf\fR.
+Valid options are:
+
+.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
+\(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.lacme\(rq if the XDG_RUNTIME_DIR
+environment variable is set.
+
+.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.
+
+.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.
+
+.TP
+.I command
+Path to the ACME client executable.
+Default: \(lq/usr/lib/lacme/client\(rq.
+
+.TP
+.I server
+Root URI of the ACME server.
+Default: \(lqhttps://acme\-v01.api.letsencrypt.org/\(rq.
+
+.TP
+.I timeout
+Timeout in seconds after which the client stops polling the ACME server
+and considers the request failed.
+Default: \(lq10\(rq.
+
+.TP
+.I SSL_verify
+Whether to verify the server certificate chain.
+Default: \(lqYes\(rq.
+
+.TP
+.I SSL_version
+Specify the version of the SSL protocol used to transmit data.
+
+.TP
+.I SSL_cipher_list
+Specify the cipher list for the connection.
+.RE
+
+.TP
+\(lq[webserver]\(rq section
+This section is used for configuring the ACME webserver.
+
+.RS
+.TP
+.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
+.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
+.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
+.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
+.I command
+Path to the ACME webserver executable.
+Default: \(lq/usr/lib/lacme/webserver\(rq.
+
+.TP
+.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 \fBlacme\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 \fBlacme\fR uses the first existing
+configuration file among \fI./lacme\-certs.conf\fR,
+\fI$XDG_CONFIG_HOME/lacme/lacme\-certs.conf\fR (or
+\fI~/.config/lacme/lacme\-certs.conf\fR if the XDG_CONFIG_HOME
+environment variable is not set), and
+\fI/etc/lacme/lacme\-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.
+
+.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:
+
+.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.
+
+
+.TP
+.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/lacme/lets\-encrypt\-x3\-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
+.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 lacme new-reg mailto:noreply@example.com
+    ~$ sudo lacme reg=/acme/reg/137760 --agreement-uri=https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf
+    ~$ sudo lacme new-cert
+    ~$ sudo lacme revoke-cert /path/to/server/certificate.pem
+.fi
+
+
+.SH SEE ALSO
+\fBlacme\-accountd\fR(1)
+
+.SH AUTHOR
+.ie \n[www-html] \{\
+  Written by
+. MTO guilhem@fripost.org "Guilhem Moulin" .
+\}
+.el \{\
+  Written by Guilhem Moulin
+. MT guilhem@fripost.org
+. ME .
+\}