Summary
OpenBSD's acme-client
acme-client
is the default Automatic Certificate Management Environment (ACME) client on OpenBSD, installed at the same time when the OS is.
To configure acme-client.conf is easy and enables us to get certificates with Let's Encrypt or another.
The basic usage is:
# # configure
# nvim /etc/acme-client.conf
# # get or update (for renewal) certificate
# acme-client <domain>
# # revoke certificate
# acme-client -r <domain>
How about CertBot
Besides, we know there is another option. Yes, CertBot by EFF (Electronic Frontier Foundation), a very popular client. Although we can get it via pkg_add certbot
, there was sometimes a problem around permissions on OpenBSD when renewing the certificate.
Environment
- OS: OpenBSD 7.0
- ACME client: OpenBSD acme-client
- Certificate Authority: Let's Encrypt
- Web server: OpenBSD httpd
How to use
Configure acme-client.conf
Well, let's see the conf file which is officially provided by OpenBSD.
$ cat /etc/examples/acme-client.conf
There are clear examples:
#
# $OpenBSD: acme-client.conf,v 1.4 2020/09/17 09:13:06 florian Exp $
#
authority letsencrypt {
api url "https://acme-v02.api.letsencrypt.org/directory"
account key "/etc/acme/letsencrypt-privkey.pem"
}
authority letsencrypt-staging {
api url "https://acme-staging-v02.api.letsencrypt.org/directory"
account key "/etc/acme/letsencrypt-staging-privkey.pem"
}
authority buypass {
api url "https://api.buypass.com/acme/directory"
account key "/etc/acme/buypass-privkey.pem"
contact "mailto:me@example.com"
}
authority buypass-test {
api url "https://api.test4.buypass.no/acme/directory"
account key "/etc/acme/buypass-test-privkey.pem"
contact "mailto:me@example.com"
}
domain example.com {
alternative names { secure.example.com }
domain key "/etc/ssl/private/example.com.key"
domain full chain certificate "/etc/ssl/example.com.fullchain.pem"
sign with letsencrypt
}
Let's copy it:
$ # well, you can see there is none by default
$ ls /etc/acme-client*
$ doas cp -p /etc/examples/acme-client.conf /etc/
Then edit:
$ doas nvim /etc/acme-client.conf
like below:
- domain example.com {
- alternative names { secure.example.com }
- domain key "/etc/ssl/private/example.com.key"
- domain full chain certificate "/etc/ssl/example.com.fullchain.pem"
- sign with letsencrypt
- }
+ domain your.domain {
+ #alternative names { secure.example.com }
+ domain key "/etc/ssl/private/your.domain.key"
+ domain full chain certificate "/etc/ssl/your.domain.fullchain.pem"
+ sign with letsencrypt
+ }
OK. your.domain
is now ready for "sign with letsencrypt".
Start OpenBSD httpd as web server
Be sure to httpd
listens on egress:
server "your.domain" {
listen on egress port 80
# ...
}
Well, you may also find the example of httpd.conf
in /etc/examples/
.
Of course, it has to be started:
$ # case disabled:
$ doas rcctl start -f httpd
$ # case enabled:
$ doas rcctl restart httpd
Request certificate
Just run the single command below, and you will get the sweet certificate:
$ doas acme-client -v your.domain
Well, -v
is for verbose and optional.
There are other methods. How to update it:
$ # the same command above
$ doas acme-client your.domain
Moreover, how to revoke it:
$ doas acme-client -r your.domain
Notes
Periodical update is required
Remember Let's Encrypt certificate lasts only 90 days. You have to update it periodically.
One way to do so is to use cron
.
Let's Encrypt has their Rate Limits
Be careful about that Let's Encrypt has several rate limits.
For example,
- "Certificates per Registered Domain". It is 50 per week.
Also,
- "Duplicate Certificate". You can renew the same certificate up to 4 times (totally 5 times) per week.
Here is their documentation on it.
Side story: The history and the changelog
acme-client first appeared in 6.1.
In 6.5 or below (to 6.1), you had to use more options to get certificate:
$ doas acme-client -ADv your.domain
In 6.6, acme-client became to able to communicate with the v02 Let's Encrypt API. Therefore, -A
and -D
have not been necessary any more. Nice improvement.
Troubleshooting: When the challenge failed
You might sometimes see such errors and, sadly, fail:
acme-client: /etc/ssl/private/your.domain: generated RSA domain key
acme-client: https://acme-v02.api.letsencrypt.org/directory: directories
acme-client: acme-v02.api.letsencrypt.org: DNS: xxx.xxx.xxx.xxx
acme-client: dochngreq: https://acme-v02.api.letsencrypt.org/acme/authz-v3/84303399960
acme-client: challenge, token: (...), uri: https://acme-v02.api.letsencrypt.org/acme/chall-v3/84303399960/MQGXJQ, status: 0
acme-client: /var/www/acme/(...): created
acme-client: https://acme-v02.api.letsencrypt.org/acme/chall-v3/84303399960/MQGXJQ: challenge
acme-client: order.status 0
acme-client: dochngreq: https://acme-v02.api.letsencrypt.org/acme/authz-v3/84303399960
acme-client: challenge, token: (...), uri: https://acme-v02.api.letsencrypt.org/acme/chall-v3/84303399960/MQGXJQ, status: -1
acme-client: order.status -1
acme-client: dochngreq: https://acme-v02.api.letsencrypt.org/acme/authz-v3/84303399960
acme-client: Invalid response from http://your.domain/.well-known/acme-challenge/(...) [2606:4700:3031::6815:3ae6]: \\"\\u003c!DOCTYPE html\\u003e\\\\n\\u003chtml\\u003e\\\\n\\u003chead\\u003e\\\\n\\u003cmeta charset=\\\\\\"utf-8\\\\\\"\\u003e\\\\n\\u003ctitle\\u003e404 Not Found\\u003c/title\\u003e\\\\n\\u003cstyle type=\\\\\\"text/css\\\\\\"\\u003e\\u003c!--\\\\nbody { background-\\"
acme-client: bad exit: netproc(87417): 1
It is 404 aka page-is-missing error. In other cases, it may 403 aka access-is-denied.
They are because your web server returned "bad response". Let's mitigate it by properly mapping response challenges:
server "your.domain" {
listen on egress port 80
+ # acme-client
+ location "/.well-known/acme-challenge/*" {
+ root "/acme"
+ request strip 2
+ }
# ...
}
Then restart httpd:
$ # case disabled:
$ doas rcctl -f restart httpd
$ # case enabled:
$ doas rcctl restart httpd
It must be fixed.
# acme-client -v your.domain
I hope you meet success like this:
acme-client: https://acme-v02.api.letsencrypt.org/directory: directories
acme-client: acme-v02.api.letsencrypt.org: DNS: xxx.xxx.xxx.xxx
acme-client: dochngreq: https://acme-v02.api.letsencrypt.org/acme/authz-v3/84304202350
acme-client: challenge, token: (...), uri: https://acme-v02.api.letsencrypt.org/acme/chall-v3/84304202350/NVmlRA, status: 0
acme-client: /var/www/acme/(...): created
acme-client: https://acme-v02.api.letsencrypt.org/acme/chall-v3/84304202350/NVmlRA: challenge
acme-client: order.status 0
acme-client: dochngreq: https://acme-v02.api.letsencrypt.org/acme/authz-v3/84304202350
acme-client: challenge, token: (...), uri: https://acme-v02.api.letsencrypt.org/acme/chall-v3/84304202350/NVmlRA, status: 2
acme-client: order.status 1
acme-client: https://acme-v02.api.letsencrypt.org/acme/finalize/58118741/68735636600: certificate
acme-client: order.status 3
acme-client: https://acme-v02.api.letsencrypt.org/acme/cert/(...): certificate
acme-client: /etc/ssl/your.domain: created
Conclusion
You have got the Let's Encrypt certificate! All what to do is add it to httpd.conf
.
server "your.domain" {
listen on * port 80
# acme-client
location "/.well-known/acme-challenge/*" {
root "/acme"
request strip 2
}
+ block return 301 "https://$SERVER_NAME$REQUEST_URI"
}
+ server "your.domain" {
+ listen on * tls port 443
+ tls {
+ certificate "/etc/ssl/your.domain.fullchain.pem"
+ key "/etc/ssl/private/your.domain.key"
+ }
+ # acme-client
+ location "/.well-known/acme-challenge/*" {
+ root "/acme"
+ request strip 2
+ }
+ # ...
+ }
Here, I replaced egress
with *
to apply also to lo
. It is optional.
Your TLS connection based on encryption aka HTTPS is completed.
Happy connecting securely🕊
Top comments (0)