Lead Image © Stuart Miles, 123RF.com

Lead Image © Stuart Miles, 123RF.com

Obtain certificates with acme.sh

Simply Certified

Article from ADMIN 65/2021
We take a close look at acme.sh, a lightweight client for the ACME protocol that facilitates digital certificates for secure TLS communication channels.

The Automatic Certificate Management Environment (ACME) protocol is mostly mentioned in connection with the Let's Encrypt certification authority because it can be used to facilitate the process of issuing digital certificates for TLS encryption. In the meantime, more and more systems have started to support ACME.

Data transmitted on the Internet ideally should be encrypted. The Let's Encrypt organization [1] has played a significant role in making this good idea a reality. Until a few years ago, obtaining an X.509 certificate was a fairly complex process, but this workflow has been greatly simplified by the Let's Encrypt certification authority in combination with the ACME protocol. Anyone can now obtain a certificate for their own web service – or even other services – to ensure secure TLS communication channels.

Basically, two components are indispensable when using ACME: an ACME server and an ACME client. The protocol requires the client to prove that it has control over the domain for which the server is to issue a certificate. If the client can provide evidence, the server issues what is known as a Domain Validated Certificate (DV) and sends it to the client. Unlike the Organization Validation (OV) or Extended Validation (EV) certificate types, for example, no validation of the applicant is necessary, so the conditions are ideal for automating the process from application through the issuing of the certificate.

Different Challenge Types

The client proves control over a domain when it responds appropriately to a challenge sent by the server. The HTTP-01 and DNS-01 challenges have been part of the ACME protocol from the outset and are therefore documented in RFC8555 [2]; the TLS-ALPN-01 challenge was only added last year as an extension to the protocol. This challenge type is described in RFC8737 [3].

Most ACME clients default to the HTTP-01 challenge because it has the lowest requirements. The requester must have a web server that can be reached from the Internet on port 80 and is configured for the domain for which the certificate is to be issued. For test purposes, the ACME client itself can also start a temporary web server.

If the requirement is not met (e.g., because access to port 80 is not possible), either the DNS-01 or TLS-ALPN-01 challenge type can be used. For DNS-01, you must be able to provision a DNS TXT record within your own domain. Alternatively, for the TLS-ALPN-01 challenge type, the client uses Application Layer Protocol Negotiation (ALPN) and generates a temporary certificate used for the period of provisioning and later replaced by the certificate issued by the ACME server. In this case, communication between the ACME server and client takes place over port 443.

Verification of Control

Regardless of the challenge type used, it is always important to allow the ACME server access to a specific resource, which it recreates for each challenge and then sends to the client for provisioning. This resource is available on the client as a file with the HTTP-01 challenge type, which the server then tries to retrieve. If, on the other hand, the DNS-01 challenge type is used, the server attempts to verify the resource with a DNS query.

Multilevel Workflow

JSON messages are used for communication between the ACME client and server. The workflow involves a client first registering with the server and then requesting the desired certificate. The client then uses the desired challenge type to prove that it has control over the domain used in the certificate. Before enrollment, the client must generate an asymmetric key pair to sign or verify the messages exchanged between the client and the server.

Each ACME server provides a Directory JSON object that ACME clients can use to query the services offered by the server, or you can also accomplish this with the use of curl or a similar tool:

curl -s https://server.example.com/acme/directory |python -m json.tool

The resource addressed earlier comprises a token that the server sends to the client and a hash generated from your public key. If you use the HTTP-01 challenge type, the ACME client must ensure that the server can request this resource under the path /.well-known/acme-challenge/ over HTTP. If you use the DNS-01 challenge type, the server expects the string in a DNS TXT record, such as:

_acme-challenge.www.example.org. 300 IN TXT "Y5YvkzC_4qh9gKj6...jxAjEuX1"

Additionally, the protocol uses nonces to protect against replay attacks and provides a workflow for revoking issued certificates, if necessary. More information can be found in RFC8555 [2]. Although you do not need to know all the protocol details for day-to-day operation, it often helps with troubleshooting.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.

Learn More”>


		<div class=