UPDATE: The letsencrypt.sh script has been renamed to dehydrated. Make sure you are using the updated dehydrated script if you are following this guide.
The Let’s Encrypt project has recently unveiled support for the DNS-01 challenge type for issuing certificates and the official Let’s Encrypt project added support with the recent addition of this PR on Github, which enables challenge support on the server side of things but does not enable the challenge in the client (yet). This is great news for those that are looking for more flexibility and additional options when creating and manage LE certificates. For example, if you are not running a web server and rely strictly on having a DNS record to verify domain ownership, this new DNS challenge option is a great alternative.
I am still learning the ins and outs of LE but so far it has been an overwhelmingly positive experience. I feel like tools like LE will be the future of SSL and certificate creation and management, especially as the ecosystem evolves more in the direction of automation and various industries continue to push for higher levels of security.
One of the big issues with implementing DNS support into a LE client as it currently stands is the large range of public DNS providers that have no standardized API support. It becomes very difficult to automate the process of issuing and renewing certificates with the lack of standardization and API’s using LE. The letsencrypt.sh project mentioned below is nice because it has implemented support for a few of the common DNS providers (AWS, CloudFlare, etc.) as hooks which allow the letsencrytpt.sh client to connect to their API’s and create the necessary DNS records. Additionally, if support for a DNS provider doesn’t exist it is easy to add it by creating your own custom hooks.
letsencrypt.sh is a nice choice because it is flexible and just works. It is essentially an implementation of the LE client, written in bash. This is an attractive option because it is well documented, easy to download and use and is also very straight forward. To use the DNS feature you will need to create a hook, which is responsible for placing the correct challenge in your DNS record.
Here is an example hook that is used for connecting with AWS Route53 for issuing certificates for subdomains. After downloading the example hook script, you need to run a few commands to get things working. You can grab it with the following command.
curl -o route53.rb https://gist.githubusercontent.com/tache/3b6760784c098c9139c6/raw/33fe6e0791a7d40ce7cdf14019b7d31801d4ab05/hook.rb chmod +x route53.rb
You also need to make sure you have the Ruby dependencies installed on your system for the script to work. The process of installing gems is pretty simple but there was an issue with the version of awesome_print at the time I made this so I had to install a specific version to get things working. Otherwise, the installation of the other gems was straight forward. NOTE: These gems are specific to the rout53.rb script. If you use another hook that doesn’t require these dependencies you can skip the gems installations.
sudo gem install awesome_print -v 1.6.0 sudo gem install aws-sdk sudo gem install pry sudo gem install domainatrix
After you install the dependencies, you can run the letsencrypt script .
./letsencrypt.sh
You can see a few different options in this command.
The following command specifies the domain in the command (rather than adding a domains.txt file to reference), the custom hook that we have downloaded, and specifies the type of challenge to use, which is the dns-01 challenge.
./letsencrypt.sh --cron --domain test.example.com --hook ./route53.rb --challenge dns-01
Make sure you have your AWS credentials configured, otherwise the certificate creation will fail. Here’s what the output of a successful certificate creation might look like.
#
# !! WARNING !! No main config file found, using default config!
#
Processing test.example.com
+ Signing domains...
+ Generating private key...
+ Generating signing request...
+ Requesting challenge for test.example.com...
-------------------->
Domain: test.example.com
Root: example.com
Stage: deploy_challenge
Challenge: yabPBE9YvPXGFjslRtqXh-qK27QlWQgFlTusqcDzUMQ
{
:change_info => {
:id => "/change/C3K8MHKLB6IRKZ",
:status => "PENDING",
:submitted_at => 2016-08-08 17:54:50 UTC
}
}
--------------------<
+ Responding to challenge for test.example.com...
-------------------->
Domain: test.example.com
Root: example.com
Stage: clean_challenge
{
:change_info => {
:id => "/change/CE90OICFSN00C",
:status => "PENDING",
:submitted_at => 2016-08-08 17:55:15 UTC
}
}
--------------------<
+ Challenge is valid!
+ Requesting certificate...
+ Checking certificate...
+ Done!
+ Creating fullchain.pem...
-------------------->
Domain: test.example.com
Root: test.example.com
Stage: deploy_cert
Certs: /Users/jmreicha/test/letsencrypt.sh/certs/test.example.com/cert.pem
--------------------<
+ Done!
The entire process of creation and verification should take less than a minute and when it’s done will drop out a certificate for you.
Here is a dump of the commands used to get from 0 to issuing a certficiate with the dns-01 challenge, assuming you already have AWS set up and configured.
git clone https://github.com/lukas2511/letsencrypt.sh.git cd letsencrypt curl -o route53.rb https://gist.githubusercontent.com/tache/3b6760784c098c9139c6/raw/33fe6e0791a7d40ce7cdf14019b7d31801d4ab05/hook.rb chmod +x route53.rb sudo gem install aws-sdk pry domainitrix awesome_print:1.6.0 ./letsencrypt.sh --cron --domain yourdomain.example.com --hook ./route53.rb --challenge dns-01
Conclusion
There are other LE clients out there that are working on implementing DNS support including LEGO and Let’s Encrypt (now called certbot), with more clients adding the additional support and functionality all the time. I like the letsencrypt.sh script because it is simple, easy to use, and it just works out of the box,with only a few tweaks needed.
As mentioned above, I have a feeling that automated certificates are the future as automation is becoming increasingly more common for these traditionally manual types of administration tasks. Getting to know how to issue certificates automatically and learning how to use the tooling to create them is a great skill to have for any DevOps or operations person moving forward.
