lancer
is a tool which will quickly and simply provision certificates for any
number of hosts in a domain, using Let's Encrypt, assuming that you have an
API-controlled DNS service.
You have too many computers. Too many (all) of them have to talk to the Internet. And, as we all know, any computer on the internet needs a TLS certificate and the lock icon that comes with it if you want to be able to talk to it.
For example:
- Maybe you have an OpenWRT router and you need to administer its web interface; you don't want to get your DNS hijacked and find that it needs.
- Maybe you need to test some web APIs that don't work without HTTPS, so you need a development certificate for localhost.
Previously the way you'd address problems like this would be to:
⚠️ 😡⚠️ use a garbage self-signed root and click through annoying warnings all the time- 🔒️🗑️🔒️ add a garbage self-signed root to your trust store
- 🔥😱🔥 turn off certificate validation entirely in your software
These are all bad in similar ways: they decrease your security and they require fiddly, machine-specific configuration that has to be repeated on every new machine that needs to talk to such endpoints.
Let's Encrypt is 99% of the solution here. And, for public-facing internet
services, it's almost trivially easy to use; many web servers provide built-in
support for it. But you don't want to use production certificates for your
main website on your development box: you want to put an entry in /etc/hosts
under a dedicated test domain name, and you shouldn't have to figure out how to
route inbound public traffic to a web server on that host name in order to
respond to a challenge.
Luckily, Let's Encrypt offers DNS-01 validation, so all you need to do is update a DNS record. Lancer uses this challenge.
Your DNS needs to be hosted on a platform that supports libcloud
(Rackspace
DNS and CloudFlare are two that I have tested with), or Gandi's' V5 API which
Lancer has specific support for. You will need an API key.
pip install lancer
mkdir certificates-for-mydomain.com
- Create empty files for the certificates you want to provision:
touch certificates-for-mydomain.com/myhost1.lan.mydomain.com.pem certificates-for-mydomain.com/myhost2.lan.mydomain.com.pem
. lancer certificates-for-mydomain.com
Upon first run, lancer will ask you 4 questions:
- what driver do you want to use? this should be the libcloud driver name, or 'gandi' for the Gandi V5 API.
- what is your username?
- what is the DNS zone that you will be provisioning certificates under?
(usually this is the registrable part of the
domain name; if you want certificates for
lan.somecompany.com
then your zone is usuallysomecompany.com
) - what is your API key? This will be prompted for and stored with Secretly, which uses Keyring to securely store secrets; this may mean that in certain unattended configurations you might need keyrings.alt to store your API key in a configuration file rather than something like Keychain or GnomeKeyring.
It will store the answers to the first three questions in
certificates-for-mydomain.com/lancer.json
and the secrets depending upon your
keyring configuration, so you shouldn't need to answer them again (although you
may need to click through a security confirmation on subsequent attempts to
allow access to your API key).
Wait for lancer
to log that it has successfully provisioned your
certificates, and copy your now-no-longer-empty .pem
files (which will each
contain a certificate, chain certificates, and a private key) to wherever you
need them on your LAN. You can kill it with ^C
or you can just leave it
running in the background and let it auto-renew every 90 days or so.
If you don't leave it running, to renew your certificates when they've expired,
simply run lancer certificates-for-mydomain.com
again, and any expired or
soon-to-expire .pem
files in that directory will be renewed and replaced.
You can add new certificates at any time by creating new, empty
fully-qualified-domain-name.pem
files,