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