LetsEncrypt with OpenBSD

You’ve probably heard the term “SSL Certificate” to describe an electronic document that is issued by a Certificate Authority (“CA”) and is used by web sites to make them “safer”. In reality, “SSL” has been superceded by TLS but old habits die hard and TLS Certificates are still referred to as “SSL Certificates”. It’s a bit like “Frankenstein” – Dr Frankenstein was the creator of the monster in Mary Shelley’s classic novel. Shelley never gave a name to Dr Frankenstein’s creation but people still use “Frankenstein” to refer to the monster in her book.

While TLS assists in making the web secure, in itself, TLS does not make the web secure. TLS just ensures (1) that the web site that claims to be the domain name (eg. brainsnapped.com) really is that domain, ie. you haven’t been maliciously re-directed to a site claiming to be what it’s not, and (2) that the connection between client (browser) and server (web site) is encrypted so that transmission of sensitive data (eg. usernames and passwords) is secure from anyone who can sniff the connection.

The encryption comes after the authentication. Authentication is done by the client (browser) checking the signature of the certificate (provided by the server) with the CA that the certificate says it was issued by. If that CA is in the browser’s list of trusted CAs, then you get the little ‘padlock’ appearing in the browser’s address bar and away you go. If the CA is not recognised by your browser then, of course, you get a warning as such and you can then decide what you want to do from there (eg. add it to your browser’s list of trusted CAs, go the site regardless, or not continue with the web site at all).

Getting a certificate from a CA costs money. UNLESS that CA happens to be LetsEncrypt (“LE”). LE was set up by the Free Software Foundation as a way to promote a safer web by making Certificates accessible to anyone. Certificates from LE are free. You don’t pay a penny. The quid pro quo is that getting one in the first instance is a bit of work as they are only issued programmatically. By this, I mean you can’t go to web site, fill in a form and get one. You must use a ‘client’ software that observes the Automatic Certificate Management Environment (“ACME”) protocol. OpenBSD comes with such a client, acme-client, in its default install (located at /usr/sbin/acme-client).

The OpenBSD developers have made is soooo simple to use LE. To get a certificate from LE on OpenBSD, all you need to do is copy the example config file, /etc/examples/acme-client.config to its parent directory (/etc), modify the file contents with your domain name and run the acme-client client, ie:

# cp /etc/examples/acme-client.config /etc/
# sed -i '/alternative names/d' /etc/acme-client.conf
# sed -i 's/example.com/my.domain.name/g' /etc/acme-client.conf
# acme-client my.domain.name

Note that ‘my.domain.name’ should, of course, be the domain name for the certificate, eg. brainsnapped.com. Also note that the ‘alternative names’ line has been removed from the config. Depending upon what you want to do, you may want to keep that and edit it with your favourite text editor. Also, you can also pass ‘-v’ or ‘-vv’ as arguments to the acme-client binary if you want to see some output when it runs. More details are available in the man page for acme-client(1) and tthe man page for acme-client.conf(5).

The results of the above will be:


To use it in your httpd.conf file you need to insert a ‘tls’ and ‘location’ macros in httpd.conf at the appropriate ‘server’ definition:

listen on * tls port 443
tls {
certificate "/etc/ssl/my.domain.name.fullchain.pem"
key "/etc/ssl/private/my.domain.name.key"
location "/.well-known/acme-challenge/*" {
  root "/acme"
request strip 2

You’ll also need to reload the httpd service:

# rcctl reload httpd

The final thing to remember is that certificates issued by LE expire after 90 days. If you intend to keep your web site operating after this period, it’s suggested you run a daily cron-job that renews it. Details are in the man page for acme-client(1).

Happy HTTPS-ing!



  1. Hello! I’m running 10-20 hosts in my homelab. I own the domain name I use for my local.mydomainname.com in my environment. Many hosts have web gui’s that require SSL certificates and the http-01 method 1) needs me to open port 80 on each machine to the www and 2) adds an extra layer of complexity to make that happen.

    I use cloudflare for my dns, and successfully use a custom API for dynamic dns (through a free bonus proxy!) currently for my vpn server.

    How do you use the dns method on BSD?

    It works nicely in pfSense and TrueNAS, but I have some iocage jails configured I’d like to also get in the game.

    I can add additional hosts to a single certificate, but automating the certificate installation seems like a tedious and fragile thing, so I’m hoping you have experience setting up acme dns plugins “from scratch” on BSD. Thanks

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: