acmed(8) — the Plan 9 manual

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

-p

provider Specifies that provider is used as the provider URL, in place of the default https://acme-v02.api.letsencrypt.org/directory. This must be the directory URL for the desired RFC8555 compliant 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 saving it unencrypted on the file system.

cat acct.key > /mnt/factotum/ctl

On the TLS server side, you can generate a RSA key and certificate 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:

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

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)

man.aiju.de 9front man pages