PFP9W/howto Permanent Floating Plan 9 Workshop

ACMED & HTTPS

This is expaining the procedure covered in the 9front FQA on running acmed to fetch a certificate so you can run an https:// web server.

acmed

The FQA says to run this;

ramfs -p

cd /tmp

auth/rsagen -t 'service=acme role=sign \
	hash=sha256 acct=user@domain.com' \
	>user@domain.com.key

auth/rsa2jwk user@domain.com.key \
	>/sys/lib/tls/acmed/user@domain.com.pub

cat user@domain.com.key > /mnt/factotum/ctl

auth/rsagen -t 'service=tls owner=*’ >domain.com.key

chmod 600 user@domain.com.key domain.com.key

cp user@domain.com.key domain.com.key \
	/sys/lib/tls/acmed/

auth/rsa2csr 'CN=domain.com' \
	/sys/lib/tls/acmed/domain.com.key \
	>/sys/lib/tls/acmed/domain.com.csr

auth/acmed -t http -o /path/to/.well-known/acme-challenge \
	user@domain.com /sys/lib/tls/acmed/domain.com.csr \
	>/sys/lib/tls/acmed/domain.com.crt

The first 2 commands are just to setup and change to a ramdisk in /tmp, so that all your keys and info aren't just laying around on the hard drive.

The next 3 are for making an account key to be used to talk to Letsencrypt to ask for a certificate, and then to load that key into factotum. Your account key has 'user@' at the front. This can be any user name you want, like 'glenda@example.com'.

The next it to make a certificate key. This is the private key to go along with the public certificate.

auth/rsagen -t 'service=tls owner=*’ >domain.com.key

I've also seen it used like this;

auth/rsagen -t 'service=tls role=client owner=*’ >domain.com.key

The next it to chmod the files so only the owner can read them, and copy them to /sys/lib/tls/acmed. There are other instruction around for stashing these in secstore if you don't want them laying on the disk.

Next is to make a certificate request that uses the certificate key made earlier. That is the key without the user name.

You can also do multiple domains at a time, just add them to the 'CN=' seperated by a comma.

The account key is in factotum, and the certificate request is generated, now to run auth/acmed which uses Letsencrypt by default to fetch a certificate. This uses http to talk to Letsencrypt, so make sure webfs is running first.

The '-o /path/to/.well-known/acme-challenge' is there because Letsencrypt will send you files, which then have to appear immediately on your website in a directory at 'http://domain.com/.well-known/acme-challenge'. This is how they verify that you do indeed have control of that web server. That path can be directly to where your website files are stored, or you can have your web server bind the verification files to the right spot. If you are running the option to get a certificate for multiple domains, you have make sure the files go into the 'http://X.domain.com/.well-known/acme-challenge' of all the domains you listed.

This command takes a few seconds to run, and if you check your web server you will see it getting requests looking for the verification files.

If everything works, you end up with a '/sys/lib/tls/acmed/domain.com.crt' file, and that is your certificate.

To renew, load the account key into factotum (the one with 'user@...'), make sure webfs is running, and run that last auth/acmed command the same as before.

HTTP & TLS

To use the certificate for running https, you will first need a listener on tcp port 443. If you are using the default /rc/bin/service, touch a file named 'tcp443' and make it executable. And write into it something that looks like this;

#!/bin/rc
exec tlssrv -c /sys/lib/tls/acmed/domain.com.crt -l /sys/log/https /rc/bin/service/tcp80 $*

This will set up a listener on port 443, the default for https, which will take a tls connection using the certificate you got, and once the connection is established, it will run that through your default web server code at tcp80.

The cert is the public end of the transaction. For it to work, it needs to be paired with your private certificate key. So the key will need to be loaded into factotum at boot. The easiest way is to add is to /cfg/$sysname/cpurc.

cat /sys/lib/tls/acmed/domain.com.key >>/mnt/factotum/ctl

You could also set up secstore and store your keys there rather then leave them out on the hard drive.

With all that in place, you should be able to load your website from 'https://domain.com', and mainstream web browsers will stop warning everyone that you are some untrusted weirdo.