path: root/usr.sbin/acme-client/acme-client.1

.\"	$OpenBSD: acme-client.1,v 1.11 2016/09/15 20:44:24 jmc Exp $
.\"
.\" Copyright (c) 2016 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 15 2016 $
.Dt ACME-CLIENT 1
.Os
.Sh NAME
.Nm acme-client
.Nd ACME client
.Sh SYNOPSIS
.Nm acme-client
.Op Fl bFmNnrv
.Op Fl a Ar agreement
.Op Fl C Ar challengedir
.Op Fl c Ar certdir
.Op Fl f Ar accountkey
.Op Fl k Ar domainkey
.Op Fl s Ar authority
.Ar domain
.Op Ar altnames
.Sh DESCRIPTION
The
.Nm
utility is an
Automatic Certificate Management Environment (ACME) client.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl a Ar agreement
Use an alternative user agreement URL.
.It Fl b
Back up all certificates in the certificate directory.
This only happens if a remove or replace operation is possible.
The backups are named
.Pa cert-NNNNN.pem ,
.Pa chain-NNNNN.pem ,
and
.Pa fullchain-NNNNN.pem ,
where
.Li NNNNN
is the current
.Ux
Epoch.
Any given backup uses the same Epoch time for all three certificates.
If there are no certificates in place, this option does nothing.
.It Fl C Ar challengedir
The directory to register challenges.
.It Fl c Ar certdir
The directory to store public certificates.
.It Fl F
Force updating the certificate signature even if it's too soon.
.It Fl f Ar accountkey
The account private key.
This was either made with a previous client or with
.Fl n .
.It Fl k Ar domainkey
The private key for the domain.
This may also be created with
.Fl N .
.It Fl m
Append
.Ar domain
to all default paths except the challenge path
.Pq i.e. those that are overridden by Fl c , k , f .
Thus,
.Ar foo.com
as the initial domain would make the default domain private key into
.Pa /etc/ssl/acme/private/foo.com/privkey.pem .
This is useful in setups with multiple domain sets.
.It Fl N
Create a new RSA domain key if one does not already exist.
.It Fl n
Create a new RSA account key if one does not already exist.
.It Fl r
Revoke the X509 certificate found in the certificates.
.It Fl s Ar authority
ACME
.Ar authority
to talk to.
Currently the following authorities are available:
.Pp
.Bl -tag -width "letsencrypt-staging" -compact
.It Cm letsencrypt
Let's Encrypt authority
.It Cm letsencrypt-staging
Let's Encrypt staging authority
.El
.Pp
The default is
.Cm letsencrypt .
.It Fl v
Verbose operation.
Specify twice to also trace communication and data transfers.
.It Ar domain
The domain name.
The only difference between this and
.Ar altnames
is that it's put into the certificate's
.Li CN
field and it uses the
.Qq main
domain when specifying
.Fl m .
.It Ar altnames
Alternative names
.Pq Dq SAN
for the domain name.
The number of SAN entries is limited to 100 or so.
.El
.Pp
Public certificates are by default placed in
.Pa /etc/ssl/acme
as
.Pa cert.pem Pq the domain certificate ,
.Pa chain.pem ,
and
.Pa fullchain.pem ,
respectively.
.Pa cert.pem
is checked for its expiration: if more than 30 days from expiry,
.Nm
does not attempt to refresh the signature.
.Pp
Challenges are used to verify that the submitter has access to
the registered domains.
.Nm
only implements the
.Dq http-01
challenge type, where a file is created within a directory accessible by
a locally-run web server.
The default challenge directory
.Pa /var/www/acme
can be served by
.Xr httpd 8
with this location block,
which will properly map response challenges:
.Bd -literal -offset indent
location "/.well-known/acme-challenge/*" {
	root "/acme"
	root strip 2
}
.Ed
.Sh FILES
.Bl -tag -width "/etc/ssl/acme/private/privkey.pem" -compact
.It Pa /etc/acme/privkey.pem
Default accountkey.
.It Pa /etc/ssl/acme
Default certdir.
.It Pa /etc/ssl/acme/private/privkey.pem
Default domainkey.
.It Pa /var/www/acme
Default challengedir.
.El
.Sh EXIT STATUS
.Nm
returns 1 on failure, 2 if the certificates didn't change (up to date),
or 0 if certificates were changed (revoked or updated).
.Sh EXAMPLES
To create and submit a new key for a single domain, assuming that the
web server has already been configured to map the challenge directory
as in the
.Sx Challenges
section:
.Pp
.Dl # acme-client -vNn foo.com www.foo.com smtp.foo.com
.Pp
A daily
.Xr cron 8
job can renew the certificates:
.Bd -literal -offset indent
#! /bin/sh

acme-client foo.com www.foo.com smtp.foo.com

if [ $? -eq 0 ]
then
	/etc/rc.d/httpd reload
fi
.Ed
.Sh SEE ALSO
.Xr openssl 1 ,
.Xr httpd.conf 5
.Sh STANDARDS
.Rs
.%U https://tools.ietf.org/html/draft-ietf-acme-acme-03
.%T Automatic Certificate Management Environment (ACME)
.Re
.Sh AUTHORS
The
.Nm
utility was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
.Sh BUGS
The challenge and certificate processes currently retain their (root)
privileges.
.Pp
For the time being,
.Nm
only supports RSA as an account key format.