plan9fox/sys/man/8/acmed

.TH ACMED 8
.SH NAME
auth/acmed \- acme certificate client
.SH SYNOPSIS
.B auth/acmed
[
.B -a
.I acctkey
]
[
.B -e
.I cmd
|
.B -o
.I chalout
.B -t
.I type
]
[
.B -p
.I provider
]
.I acctname
.I csr
>
.I crt
.SH DESCRIPTION
Acmed fetches and renews a TLS certificate
using the
.I ACME (RFC8555)
protocol.
It requires a pre-generated account key in
.IR factotum (4)
that is identified by
.I acctname
or an
.I acctkey
file.
It also needs a certificate signing request file
.I csr
in binary X.509 ASN.1/DER format
that contains the public key and subjects (domain names)
that we want to get a certificate for.
On success,
.I acmed
outputs the new certificate in
PEM format to stdandard output.
.PP
.I Acmed
accepts the following options:
.TP
.B -a
.I acctkey
Specifies that
.I acctkey
is used to sign requests to the
.I provider
in place of the default
.BI /sys/lib/tls/acme/ acctname .pub
file.
The key must be a JWK formatted RSA public key
(see
.IR rsa (8)).
.TP
.B -e
.I cmd
Specifies that an external command should be run to
install the challenge material.
The
.I cmd
is run with the following four arguments:
The challenge method,
the subject (domain),
the token,
and last the challenge response.
If
.I cmd
returns an error status,
it is assumed that it does not support the
challenge method for the given subject (domain)
and another method might be tried.
Because of this, the
.B -o
and
.B -t
options are unnecessary.
.TP
.B -o
.I chalout
Specifies that the challenge material is
placed in the location
.IR chalout .
Its behavior depends on the challenge type,
as specified with the
.B -t
flag.
.IP
For HTTP challenges,
.I chalout
must be a directory that your webserver will serve at
.br
.BI http:// mydomain.com /.well-known/acme-challenge .
.br
It defaults to
.BR /usr/web/.well-known/acme-challenge .
.IP
For DNS challenges,
.I chalout
is a file that should be included in your
.IR ndb (6)
database.
It defaults to
.BR /lib/ndb/dnschallenge .
.TP
.B -t
.I type
Specifies that the challenge type. Supported challenge
types are currently
.B http
and
.BR dns .
.TP
.B -p
.I provider
Specifies that
.I provider
is used as the provider URL, in place of the default
.BR https://acme-v02.api.letsencrypt.org/directory .
This must be the directory URL for the desired
.I RFC8555
compliant provider.
.SH EXAMPLES
Before
.I acmed
can be used, the account key must be generated:
.IP
.EX
auth/rsagen -t \\
	'service=acme role=sign hash=sha256 acct=me@example.com' \\
	> acct.key
auth/rsa2jwk acct.key > /sys/lib/tls/acmed/me@example.com.pub
.EE
.PP
Then the
.B acct.key
must be loaded into
.IR factotum(4).
It is recommended to put
.B acct.key
into
.IR secstore (1)
instead of saving it unencrypted on the file system.
.IP
.EX
cat acct.key > /mnt/factotum/ctl
.EE
.PP
On the TLS server side, you can generate a RSA key
and certificate signing request file like this:
.IP
.EX
auth/rsagen -t 'service=tls owner=*' > cert.key
auth/rsa2csr 'CN=mydomain.com' cert.key \\
	> /sys/lib/tls/acmed/mydomain.com.csr
.EE
.PP
See
.IR rsa (8)
and
.IR tlssrv (8)
for more examples on how to use RSA keys.
.IP
.PP
The certificate for the domain can now be fetched.
This requires
.IR webfs(4)
to be mounted as the ACME protocol uses HTTP
to talk to the provider.
.IP
.EX
auth/acmed me@example.com /sys/lib/tls/acmed/mydomain.com.csr \\
	> /sys/lib/tls/acmed/mydomain.com.crt
.EE
.PP
When using the DNS challenge method,
your DNS server
(see
.IR ndb (8))
must be configured,
and
.IR ndb (6)
must be setup to include the
.I chalout
file that
.I acmed
can write to:
.IP
.EX
database=
	file=/net/ndb
	file=/lib/ndb/local
	file=/lib/ndb/common
	file=/lib/ndb/dnschallenge
.EE
.PP
In addition, the domains that you like to get verified
needs to have a certificate authority authorization record
of your ACME provider declared:
.IP
.EX
dom=mydomain.com caa=letsencrypt.org
.EE
.PP
Then
.I acmed
can be invoked to fetch the certificate using the
DNS challenge method:
.IP
.EX
auth/acmed -t dns me@example.com mydomain.com.csr \\
	> /sys/lib/tls/acmed/mydomain.com.crt
.EE
.SH FILES
.BI /sys/lib/tls/acmed/ * .pub
Account public keys.
.SH SOURCE
.B /sys/src/cmd/auth/acmed.c
.SH SEE ALSO
.IR factotum (4),
.IR ndb (6),
.IR ndb (8),
.IR rsa (8),
.IR secstore (1),
.IR tlssrv (8),
.IR webfs (4).
.SH  BUGS
.PP
When using DNS challenge,
the
.B -t
.B dns
method assumes that the DNS server runs
on the same machine as
.I acmed
and that it is mounted on
.B /net
and that we have hostowner permissions to
write the
.B refresh
command to
.BR /net/dns .
Also, when using multi-domain certificates,
the usable challenge methods might be different for
individual domains.
Using the
.B -e
.I cmd
option to customize the challenge installation procedure
can be used to work around this.
.PP
.B https://bugzilla.mozilla.org/show_bug.cgi?id=647959
.SH HISTORY
.PP
.I Auth/acmed
first appeared in 9front (Oct 2021)