MAN.9FRONT.ORG RTFM


     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.

     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:

     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)