.TH LETSENCRYPT "1" "DECEMBER 2015" "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 ...]


.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.
(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.

.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).

.TP
.B \-?\fR, \fB\-\-help\fR
Display a brief help and exit.

.TP
.B \-q\fR, \fB\-\-quiet\fR
Try to be quiet.

.TP
.B \-\-debug
Turn on debug mode.


.SH ACCOUNT KEY REGISTRATION
.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-reg\fR \fIACCOUNTKEY\fR [\fIEMAIL\fR ...]

Registers the given \fIACCOUNTKEY\fR.  An optional list of \fIEMAIL\fR
addresses can be given as contact information.

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


.SH CERTIFICATE ISSUANCE
.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-cert\fR \fIACCOUNTKEY\fR
\fB\-\-output=\fICERT\fR \fB\-\-csr=\fIFILE\fR

.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]

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.

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

.TP
.B \-\-csr=\fIFILE
Certificate Signing Request to send (alternatively, use \fB\-\-key\fR to
generate it from the private server key).

.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.)

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

.TP
.B \-\-hash=\fIDGST
Message digest to sign the Certificate Signing Request with.

.TP
.B \-\-subject=\fR/\fItype0\fR=\fIvalue0\fR/\fItype1\fR=\fIvalue1\fR/\fItype2\fR=...
Subject name to use in the Certificate Signing Request.

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

.TP
.B \-\-keyusage=\fISTRING
Comma-separated list of Key Usages, see x509v3_config(5ssl).
(Default: \(lqdigitalSignature,keyEncipherment,keyCertSign\(rq.)

.TP
.B \-\-output=\fIFILE
Where to copy the issued (signed) X.509 certificate.

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

.TP
.B \-\-notify=\fICOMMAND\fR
Command to run upon success.  (This option can be repeated to run
multiple commands.)


.SH CERTIFICATE REVOKATION
.B letsencrypt\fR [\fIOPTION\fR ...] \fBrevoke\-cert\fR {\fIACCOUNTKEY\fR|\fISVRKEY\fR} \fIFILE\fR [\fIFILE\fR ...]

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.


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

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


.SH AUTHOR
Written by Guilhem Moulin
.MT guilhem@fripost.org
.ME .