acme-client.1

.\"	$Id$
.\"
.\" Copyright (c) 2016--2017 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$
.Dt ACME-CLIENT 1
.Os
.Sh NAME
.Nm acme-client
.Nd secure ACME client
.\" .Sh LIBRARY
.\" For sections 2, 3, and 9 only.
.\" Not used in OpenBSD.
.Sh SYNOPSIS
.Nm acme-client
.Op Fl beFmnNOrsv
.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 t Ar challenge
.Ar domain
.Op Ar altnames...
.Sh DESCRIPTION
The
.Nm
utility submits an X509 certificate for
.Ar domain
and its alternate DNS names
.Ar altnames
to the
.Dq Let's Encrypt
ACME server for automated signing.
It can also revoke previously-submitted signatures.
It must be run as root.
(Why?
.Xr chroot 2 . )
.Pp
By default, it uses
.Pa /var/www/acme
for responding to challenges
.Pq Fl C ,
.Pa /etc/ssl/acme
for the public certificate directory
.Pq Fl c ,
.Pa /etc/ssl/acme/private/privkey.pem
for the domain private key
.Pq Fl k ,
and
.Pa /etc/acme/privkey.pem
for the account private key
.Pq Fl f .
All of these must exist unless you use
.Fl n
and/or
.Fl N ,
which will generate the account and domain private keys, respectively.
Its arguments are as follows:
.Bl -tag -width Ds
.It Fl b
Back up all
.Sx Certificates
in the certificate directory.
This will only back up if something will be done to them (remove or
replace).
The backups are called
.Pa cert-NNNNN.pem ,
.Pa chain-NNNNN.pem ,
and
.Pa fullchain-NNNNN.pem ,
where
.Li NNNNN
is the current UNIX epoch.
Any given backup effort will use the same epoch time for all three
certificates.
If there are no certificates in place, this does nothing.
.It Fl e
Allow expanding the domains listed in the certificate.
This is a no-op if no certificate exists yet.
If a new domain is specified, the certificate will be renewed as if
.Fl F
were also specified.
.It Fl F
Force updating the certificate signature even if it's too soon.
.It Fl m
Append
.Ar domain
to all default paths except the challenge path
.Pq i.e., those that are overriden 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.
If the
.Pa foo.com
directory is not found within non-overriden default paths, it will be
created automatically.
.It Fl n
Create a new 4096-bit RSA account key if one does not already exist.
.It Fl N
Create a new 4096-bit RSA domain key if one does not already exist.
.It Fl O
Request OCSP stapling for the given domains.
.It Fl r
Revoke the X509 certificate found in
.Sx Certificates .
.It Fl s
Use the
.Dq Let's Encrypt
staging server instead of the real thing.
.It Fl v
Verbose operation.
Specify twice to also trace communication and data transfers.
.It Fl a Ar agreement
Use an alternative agreement URL.
The default uses the current one, but it may be out of date.
.It Fl C Ar challengedir
Where to register challenges.
See
.Sx Challenges
for details.
Ignored when
.Fl t
is specified.
.It Fl c Ar certdir
Where to put public certificates.
See
.Sx Certificates
for details.
.It Fl f Ar accountkey
The account private key.
This was either made with a previous ACME 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 t Ar challenge
If not using the internally-handled
.Dq http-01
as a challenge type, specify a
.Ar challenge
for the caller to manage.
See the
.Sx Challenges
section for details.
.It Ar domain
The domain name.
The only difference between this and the
.Ar altnames
is that it's put into the certificate's
.Li CN
field and that it uses the
.Dq 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 by ACME servers, usually to 100 or
so.
.El
.Pp
The process by which
.Nm
obtains signed certificates is roughly as follows.
In this, the
.Dq CA
is the ACME server for Let's Encrypt.
.Bl -enum
.It
Access the CA (unauthenticated) and requests its list of resources.
.It
Optionally create and register a new RSA account key.
.It
Read and process the RSA account key.
This is used to authenticate each subsequent communication to the CA.
.It
For each domain name,
.Bl -enum
.It
submit a challenge for authentication to the CA,
.It
create a challenge response file,
.It
wait until the CA has verified the challenge.
.El
.It
Read and extract the RSA or ECSDA domain key.
.It
Create an X509 request from the domain key for the domain and its
alternative names.
.It
Submit a request for signature to the CA.
.It
Download the signed X509 certificate.
.It
Extract the CA issuer from the X509 certificate.
.It
Download the certificate chain from the issuer.
.El
.Pp
The revocation sequence is similar:
.Bl -enum
.It
Request list of resources, manage RSA account key as in the case for
signing.
.It
Read and extract the X509 certificate (if found).
.It
Create an X509 revocation request.
.It
Submit a request for revocation to the CA.
.It
Remove the certificate, the chain, and the full-chain.
.El
.Ss Challenges
ACME uses challenges to verify that the submitter has access to the
registered domains.
.Nm
internally implements only the
.Dq http-01
challenge type, where a file is created within a directory accessible by
a locally-run web server configured for the requested domain.
This is usually
.Pa /var/www/acme .
See
.Sx EXAMPLES
for example configurations for the default challenge.
.Pp
An alternate challenge type, however, may be specified with
.Fl t ,
in which case the caller must create the challenge environment.
This may be used for implementing
.Dq dns-01
and other system-specific challenges.
.Pp
When using
.Fl t ,
each domain (primary and altnames) is authorised over standard output
and input between the caller and
.Nm
as follows:
.Bl -enum
.It
.Nm
prints
.Dq challenge-type dns-domain token.thumbprint\en
.Pq note the trailing newline
on its standard output.
.It
The caller performs any tasks to implement the challenge's response.
.It
The caller writes the same three-field string and the newline to the
standard input of
.Nm .
.El
.Pp
This cycle repeats for each requested domain, then
.Nm
exits.
.Ss Certificates
Public certificates (domain certificate, chain, and the full-chain) are
placed by default in
.Pa /etc/ssl/acme
as
.Pa cert.pem ,
.Pa chain.pem ,
and
.Pa fullchain.pem ,
respectively.
These are all created as the root user with mode 444.
.Pp
The
.Pa cert.pem
file, if found, is checked for its expiration: if more than 30 days from
expiring,
.Nm
will not attempt to refresh the signature.
.\" .Sh CONTEXT
.\" For section 9 functions only.
.\" .Sh IMPLEMENTATION NOTES
.\" Not used in OpenBSD.
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.\" .Sh FILES
.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).
.\" For sections 1, 6, and 8 only.
.Sh EXAMPLES
To create and submit a new key for a single domain, begin by setting up
your web server environment (using foo.com and www.foo.com as examples)
to use
.Pa /var/www/acme
as the challenge directory and
.Pa /etc/ssl/acme
to contain the certificates.
.Pp
An nginx configuration could be as follows:
.Bd -literal
server {
  listen 443;
  server_name foo.com www.foo.com;
  ssl_certificate /etc/ssl/acme/fullchain.pem;
  ssl_certificate_key /etc/ssl/acme/private/privkey.pem;
}
server {
  listen 80;
  server_name foo.com www.foo.com;
  location ^~ /.well-known/acme-challenge/ {
    alias /var/www/acme/;
  }
}
.Ed
.Pp
The following for Apache:
.Bd -literal
<VirtualHost *:443>
  ServerName foo.com
  ServerAlias www.foo.com
  SSLEngine on
  SSLCertificateFile /etc/ssl/acme/cert.pem
  SSLCertificateChainFile /etc/ssl/acme/fullchain.pem
  SSLCertificateKeyFile /etc/ssl/acme/private/privkey.pem
</VirtualHost>
<VirtualHost *:80>
  ServerName foo.com
  ServerAlias www.foo.com
  Alias /.well-known/acme-challenge /var/www/acme
</VirtualHost>
.Ed
.Pp
And lastly, OpenBSD's httpd:
.Bd -literal
server "www.foo.com" {
  alias "foo.com"
  listen on $ext_addr port 80
  listen on $ext_addr tls port 443
  location "/.well-known/acme-challenge/*" {
    root { "/acme", strip 2 }
  }
  tls {
    certificate "/etc/ssl/acme/fullchain.pem"
    key "/etc/ssl/acme/private/privkey.pem"
  }
}
.Ed
.Pp
Next, request a new certificate for the new domain.
.Bd -literal
# mkdir /etc/ssl/acme
# mkdir /etc/ssl/acme/private
# chmod 0700 /etc/ssl/acme/private /etc/acme
# acme-client -vNn foo.com www.foo.com
.Ed
.Pp
You'll then probably want to restart your web server to pick up the new
certificates.
You'll need to replace the rcctl statement with the correct script to
have your web server reload its certificates.
.Pp
You can then keep your certificates fresh with a daily
.Xr crontab 5
invocation:
.Bd -literal
13 1 * * * acme-client foo.com www.foo.com && rcctl reload httpd
.Ed
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.Sh SEE ALSO
.Xr openssl 1 ,
.Xr crontab 5
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
The
.Nm
utility was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
It was originally named
.Nm letskencrypt ,
renamed at version 0.1.11.
.\" .Sh CAVEATS
.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.
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.