Symbols count in article: 2kReading time: 12 mins.
In my previous 2 blogs I have shown you how to build a HTTP/2 webserver. In these blogs we have covered self signed TLS certificates as well retrieving a Certificate via Letsencrypt. I mentioned there you will have to expose your server publicly on the internet. However I now figured out there is another way. So please continue reading.
Let’s Encrypt is a free, automated, and open certificate authority brought to you by the nonprofit Internet Security Research Group (ISRG).
Letsencrypt implements the ACME (Automated Certificate Management environment) protocol. In the ACME protocol there are 4 challenge types defined. Let’s go briefly over these challenge types, so we can relate this back to my previous blogs before we are going to use the DNS challenge type.
HTTP-01 challenge
This challenge can only be performed on port 80. The client will temporarely place a file on the webserver in the following path.
/.well-known/acme-challenge/<TOKEN>
Once the ACME client tells Letsecrypt the file is there it will be retrieved to authenticate and validate. Upon success you will receive the certificate. For this challenge your webserver has to be publicly reacheable on port 80.
DNS-01 challenge
This challenge requires you to prove the ownership of a domain name. It also allows for issuing wildcard certificates. After receiving a token the client will have to create a DNS TXT record with the following contents.
_acme-challenge.<YOUR_DOMAIN>
Letsencrypt will query for this DNS record. Once verified, the client can issue the certificate. As automation is important there is a large amount of DNS providers that expose an API. For this challenge your webserver does not have to be exposes on the internet, and is therefore very convenient to issue development certificates for a domain you personally own.
TLS-SNI-01 challenge
This challenge was defined in draft versions of ACME. It did a TLS handshake on port 443 and sent a specific SNI header, looking for certificate that contained the token. It was disabled in March 2019 because it was not secure enough. So let’s quickly forget about this one.
TLS-ALPN-01 challenge
This challenge can be performed on port 443 over TLS only. This challenge is not suitable for most people. It is best suited to authors of TLS-terminating reverse proxies that want to perform host-based validation like HTTP-01, but want to do it entirely at the TLS layer in order to separate concerns.
Recap
So now we know a bit about the different ACME Challenge types lets see what we have used in the previous blog. In this blog we had to publicly expose our webserver to be able to request a certificate. The main reason for this is that the golang.org/x/crypto/acme/autocert does not offer the DNS-01 challenge implementation. We have been using the HTTP-01 challenge on this server to get our certificate.
So now lets focus on how we can issue a certificate via the DNS-01 challenge type. As a fan of the Go programming language I found a bunch of other libraries and tools implementing the ACME protocol. These do implement the DNS-01 challenge type.
Lego
Lego can be used both as a cli tool or as a library in your own code. Lego supports a whole bunch of DNS providers.
Certmagic
Certmagic is the library used in the Caddy webserver. To make use of the DNS-01 challenge also certmagic supports the Lego DNS providers.
Example
In this blog I will show you a small example using the Lego cli to issue a certificate for your domain. I’m utilizing for that the Gandi Live DNS (v5) as a DNS Provider.
First I will install Lego from sources using Go. Please note you will require Go 1.12+.
$ GO111MODULE=on go get -u github.com/go-acme/lego/v3/cmd/lego go: found github.com/go-acme/lego/v3/cmd/lego in github.com/go-acme/lego/v3 v3.5.0 ... ... ... $ lego -h NAME: lego - Let's Encrypt client written in Go USAGE: lego [global options] command [command options] [arguments...] VERSION: dev COMMANDS: run Register an account, then create and install a certificate revoke Revoke a certificate renew Renew a certificate dnshelp Shows additional help for the '--dns' global option list Display certificates and accounts information. help, h Shows a list of commands or help for one command ... ... ...
If you don’t have Go installed on your machine, there is also a Docker container available.
$ docker run goacme/lego -h NAME: lego - Let's Encrypt client written in Go USAGE: lego [global options] command [command options] [arguments...] VERSION: v3.5.0 COMMANDS: run Register an account, then create and install a certificate revoke Revoke a certificate renew Renew a certificate dnshelp Shows additional help for the '--dns' global option list Display certificates and accounts information. help, h Shows a list of commands or help for one command ... ... ...
For my Gandi Live DNS, I will have to provide my Gandi API Key to be able to communicate with their API. In below example I show you a dummy key, so don’t expect this to work for you.
$ export GANDIV5_API_KEY=G4nD1v5L1v3DNSDummyK3y $ lego --dns gandiv5 -d marcofranssen.nl -d '*.marcofranssen.nl' -a -m marco.franssen@gmail.com run 2020/04/11 13:31:42 No key found for account marco.franssen@gmail.com. Generating a P384 key. 2020/04/11 13:31:42 Saved key to /Users/marco/.lego/accounts/acme-v02.api.letsencrypt.org/marco.franssen@gmail.com/keys/marco.franssen@gmail.com.key 2020/04/11 13:31:43 [INFO] acme: Registering account for marco.franssen@gmail.com !!!! HEADS UP !!!!
Your account credentials have been saved in your Let's Encrypt configuration directory at "/Users/marco/.lego/accounts". You should make a secure backup of this folder now. This configuration directory will also contain certificates and private keys obtained from Let's Encrypt so making regular backups of this folder is ideal.
2020/04/11 13:36:11 [INFO] [mac-dev.marcofranssen.nl] acme: Obtaining bundled SAN certificate 2020/04/11 13:36:12 [INFO] [mac-dev.marcofranssen.nl] AuthURL: https://acme-v02.api.letsencrypt.org/acme/authz-v3/3894178945 2020/04/11 13:36:12 [INFO] [mac-dev.marcofranssen.nl] acme: Could not find solver for: tls-alpn-01 2020/04/11 13:36:12 [INFO] [mac-dev.marcofranssen.nl] acme: Could not find solver for: http-01 2020/04/11 13:36:12 [INFO] [mac-dev.marcofranssen.nl] acme: use dns-01 solver 2020/04/11 13:36:12 [INFO] [mac-dev.marcofranssen.nl] acme: Preparing to solve DNS-01 2020/04/11 13:36:13 [INFO] API response: DNS Record Created 2020/04/11 13:36:13 [INFO] [mac-dev.marcofranssen.nl] acme: Trying to solve DNS-01 2020/04/11 13:36:13 [INFO] [mac-dev.marcofranssen.nl] acme: Checking DNS record propagation using [8.8.8.8:53 8.8.4.4:53] 2020/04/11 13:36:13 [INFO] Wait for propagation [timeout: 20m0s, interval: 20s] 2020/04/11 13:36:14 [INFO] [mac-dev.marcofranssen.nl] acme: Waiting for DNS record propagation. 2020/04/11 13:36:34 [INFO] [mac-dev.marcofranssen.nl] acme: Waiting for DNS record propagation. 2020/04/11 13:36:54 [INFO] [mac-dev.marcofranssen.nl] acme: Waiting for DNS record propagation. 2020/04/11 13:37:14 [INFO] [mac-dev.marcofranssen.nl] acme: Waiting for DNS record propagation. 2020/04/11 13:37:41 [INFO] [mac-dev.marcofranssen.nl] The server validated our request 2020/04/11 13:37:41 [INFO] [mac-dev.marcofranssen.nl] acme: Cleaning DNS-01 challenge 2020/04/11 13:37:41 [INFO] [mac-dev.marcofranssen.nl] acme: Validations succeeded; requesting certificates 2020/04/11 13:37:42 [INFO] [mac-dev.marcofranssen.nl] Server responded with a certificate.
Now lets inspect the certificate we received. Please note there is also a .key file in the same location which you will have to deploy at your webserver. For security reasons I will not share my key over here.
Last but not least you can very easily renew your certificate using Lego.
1 2
$ lego --dns gandiv5 -d mac-dev.marcofranssen.nl -a -m marco.franssen@gmail.com renew 2020/04/11 13:49:23 [mac-dev.marcofranssen.nl] The certificate expires in 89 days, the number of days defined to perform the renewal is 30: no renewal.
Feel free to explore the other options of the cli yourself. There are plenty of DNS providers available.
Last but not least you will have to update your /etc/hosts file to use the certificate on your laptop during development.
Thanks for reading my blog, don’t forget to share with your friends and colleagues. Together we can make the web a safer place, and this starts with your development, so you can use modern web features such as HTTP/2 and gRPC, which require you to use TLS.