path: root/lacme.1

.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 .
\}