We work on a product called Bahmni and a lot of our customers are in a rural intranet setup. We have a web application that is hosted on the intranet. We wanted to help our customers generate the SSL/TLS certificate using LetsEncrypt and make the application secure. Before LetsEncrypt, getting and maintaining the certificates was painful and costly.
LetsEncrypt is a CA that provides a free, open and automated way of generating SSL/TLS certificates
The Objective of LetsEncrypt and ACME is to make the generation of these certificates as easy and automated as possible without human intervention.
What is ACME?
ACME stands for “Automatic Certificate Management Environment”. Traditionally, the SSL Certificates are issued by a CA using some sort of manual and adhoc processes. They verify the domain names in both online and offline methods to check for the correct owner of the domain before issuing the certificates.
ACME came up with a protocol that provides an automated way of verifying whether the domain name belongs to the entity that is requesting for the SSL/TLS certificates. Please note that “Application of Certificate” and “Certificate Issuance” are only few functions of ACME. Please refer to this document for more information on other functions like “Certificate Revocation”.
How it works?
ACME allows the client to request for certificates using a set of JSON messages (with JWS for additional security) over HTTPS. The following is the process of certificate issuance in simple words.
- The ACME Client requests for the certificate.
- The server responds with a list of requirements that the client has to comply with. For example, the server requires the client to prove its ownership of the domain name (i.e. they are the real owner of the domain and they have access to manage the DNS entries).
- Once the client responds to the challenges posed by the server, the validation process will be complete. The server proactively issues the certificates or sometimes the server waits for the client to finalize the application and then issues the certificates
Understanding the “ACME Challenges”
ACME server has exposed some REST Services for handling the clients like Registration Resources, Application Resource, Authorization Resource, Challenge Resource etc. Some actions that can be accomplished using these resources are “account registration”, “apply for cert”, “fetch challenges” etc. The protocol is still in draft stage and there might be some changes by final version.
As discussed in the previous section, the identifier authorization process (here the identifier is the domain name authorization) involves sending a request, the server responds with a list of challenges. The client will then respond to the challenge claiming the ownership of the identifier (domain name in this case). The following are various identifier validation challenges supported
- HTTP Challenge —The ACME client proves its ownership of the domain name by listening for requests on a HTTP server that is associated to the domain. i.e. this HTTP server should be on the internet and its IP is associated to the domain name for which we are requesting the SSL certificates. The ACME client and Server will communicate, the server responds by accessing the domain-name and once the handshake is complete, the SSL Certificates are generated.
- TLS with Server Name Identification Challenge — The ACME client needs to configure a TLS Server whose IP address is associated to the domain. Overall process is similar to the above challenge.
- DNS Challenge — The ACME client needs to prove the domain validation by proving the access to DNS server. In this challenge, the client has to create a TXT record under the specific domain name, containing a designated value available as part of the challenge.
The best part is that, the ACME client need not be hosted on the internet with a public IP. All you need is ability to add TXT record either manually or in automated fashion. This is best suited for Intranet based apps which needs SSL Certificate and doesn’t have a public IP.
4. Out-Of-Band Challenge — This challenge is for them who needs some manual intervention in validating the domain name. The server responds with a URL which needs to be accessed by a human and continue with validation.
- Certbot currently supports HTTP & TLS Challenge. As of this writing, they added support for DNS Challenge in the master branch of the codebase, but it is still not released.
- As mentioned, if you want to install the certificates on a server in the Intranet, you can use acme.sh or letsencrypt.sh which support DNS Challenge. Its pretty simple and straightforward. These scripts provide an automated way of updating the DNS “TXT” record for DNS providers which can be accessed through API.
For example, the following is a snippet of generating certs using acme.sh
Disclaimer: The views and opinions expressed by the author are personal to the author and do not necessarily reflect the positions of ThoughtWorks.