(1 votes, average: 5.00 out of 5, rated)

Loading...

• Facebook
• Twitter
• LinkedIn
• Mail

May 31, 2019 3

ACME Protocol: What it is and how it works

in Everything Encryption

Automated Certificate Management Environments explained.

The ACME (Automated Certificate Management Environment) protocol was originally developed by the Internet Security Research Group for its public CA, Let’s Encrypt.

ACME is what facilitates Let’s Encrypt’s entire business model, allowing it to issue 90-day domain validated SSL certificates that can be renewed and replaced without website owners ever having to lift a finger.  

In March of this year the ACME protocol was finally published as an internet standard (RFC 8555) and now we’re starting to see commercial CAs support it. Including one of our biggest partners, Sectigo (formerly Comodo CA), which is currently beta testing its support for the protocol before a planned full launch this Summer.

Obviously – given the fact Sectigo offers business authentication SSL/TLS certificates in addition to other X.509 certificates like S/MIME, Code Signing, etc. – the use case for the ACME protocol is about to change quite a bit. But that’s to the benefit of corporate and enterprise clients with massive infrastructures and considerable digital certificate needs.

So, today we’re going to spend some time introducing the uninitiated to the ACME protocol, explaining what it does, how it works and why it’s going to change the way organizations manage their digital certificates forever.

Let’s hash it out.

What is the ACME protocol?

For the vast majority of people that don’t spend their time focusing on PKI and digital certificates, mention of the word “ACME” probably calls to mind the fictional organization that used to ship Wile E. Coyote products for all those harebrained schemes that inevitably failed to get him a taste of that sweet, stringy road runner meat.

Obviously, we’re not talking about that ACME, enjoyable as discussing business ethics in the Looney Tune-iverse might be.

Let’s start with sort of an executive summary and then we’ll drill down into the specifics further down the page.

The ACME protocol functions by installing a certificate management agent on a given web server. The organization or domain undergoes validation at the outset, with the agent assisting with the domain control verification aspects, and once completed the agent can request, renew and revoke certificates.

The way that process works is that the agent generates a key pair and shares it with the CA at the outset of the validation process. Once validation is finished and the agent is verified as the proven owner of the key pair, it can use its key to digitally sign the CSRs it generates and sends to the CA via HTTPS requests. The CA uses the CSR, along with its associated public key, to issue the certificate and send it back to the agent. The agent downloads and installs it, then notifies the designated contact.

The agent can be automated to check in with the CA at given intervals to rotate certificates and keys. None of this requires human intervention. Agents can be installed on any server that uses X.509 certificates and can handle multiple domains on the same server; or agents can be installed on a domain-by-domain basis.

This knocks out about 95% of the labor typically involved with requisitioning digital certificates, which can be a massive savings at scale.

Now let’s drill down a little deeper.

How does the ACME protocol work?

There’s really two explanations for this question. There’s a high-level one that just covers the basics and then there’s a more in-depth one that covers the technical side. We’re going to try to keep this high level.

Once you get the ACME agent installed and configured properly, it’s actually pretty simple. We’ll talk about setup in a minute, but for now just keep in mind that during the verification process that takes place when the agent is installed a key pair will be generated for use by the agent and the CA. Those keys are sometimes referred to as “authorization keys.”

Issuance/Renewal

To get a digital certificate issued, the agent simply needs to generate a CSR for the desired domain and send it along to the CA. This is done via HTTPS.

1. The agent generates a CSR for the domain
2. The agent signs the public key generated alongside the CSR with the corresponding private key
3. The agent signs the whole CSR with its own private key (the authorization key generated during initial configuration)
4. The CA verifies both signatures and issues the certificate
5. The agent receives the certificate and installs it on the relevant domain

I realize that the agent we’re discussing is definitely not a little person that resides on your server like the icons I’ve chosen might indicate. So, there’s no need to point that out. It’s just more amusing to imagine that way.

Anyway, this process plays out more or less the same with renewals, as well. The agent can be configured to ping the CA at regular intervals to either rotate keys or swap out entire certificates. And this is all done behind the scenes, without the need for any human intervention.

Revocation

Much like getting a certificate issued, getting one revoked requires the agent to sign a request with its private key – just in this case it’s a revocation request. The CA verifies the signature, revokes the certificate and then publishes that information to the requisite Certificate Revocations Lists (CRLs) and Online Certificate Status Protocol responders (OCSPs). These are the mechanisms that browsers use to check the validity of SSL/TLS certificates.

1. The agent generates a revocation request for the SSL/TLS certificate
2. The agent signs the request with its private key
3. The CA verifies the signature to ensure the request is authorized
4. The CA revokes the certificate
5. The certificate’s revocation status is published to CRLs and OCSP responders

There are scenarios where the admin or employee responsible for overseeing certificate management may have to initiate the revocation request, but after that everything is hands-off.

Setting up ACME

Ok, now let’s get into what setup looks like when you decide to start using the ACME protocol. The very first thing you’re going to need to decide on is what client you want to use. There are dozens of different clients that run in every conceivable language and environment.

Despite the fact Let’s Encrypt was the first to leverage the ACME protocol – and despite the fact it was designed by its parent organization – it’s open source. There is no proprietary client for any of the CAs. Rather the protocol is designed to give the user their pick of Certificate Authorities, provided that CA supports it.

We’re currently on v2 of the protocol, which was published around a year ago in March of 2018. ACME v2 is not backwards compatible with ACME v1. In addition to overhauling some of its existing functions for the sake of a more streamlined user experience, v2 also added the ability to issue Wildcard SSL/TLS certificates, albeit with a rather strict DNS text record challenge.

Challenges, in the context of ACME, refers to the tests given by the CA to verify the agent’s control over a given domain. More on that in a minute.

Here’s a list of some of the most popular ACME v2 clients:

• Certbot
• ACMESharp
• acme-client
• GetSSL
• Posh-ACME
• Caddy
• Sewer
• nginx ACME
• node-acme-lambda
• peter_sslers

The last one made the cut for the name alone.

Let’s get back to setting up your domain/server to use the ACME protocol. Now that you’ve chosen the client you want to use and installed it on your server, we can get into the configuration.

1. The client will prompt you to enter the domain(s) it will be managing
2. The client will offer a list of Certificate Authorities that support the ACME protocol
3. Once a CA is selected, the client contacts the CA and generates an authorization key pair
4. The CA will issue challenges (DNS or HTTPS) requiring the agent to take an action that demonstrates control over said domain(s)
5. In addition to the challenges, the CA also sends a nonce – a randomly generated number – that the agent must sign with the private key it just generated to demonstrate ownership of said key pair

Once the CA is able to verify that the challenges have been satisfied and the signature is authentic, the agent is officially authorized to act on behalf of the validated domains. All-in-all the whole process takes maybe 10 minutes. From there, just make the configurations you want in terms of how frequently the agent will contact the CA to rotate or renew certificates, etc.

This is where having pre-defined security policies comes in handy.

Common ACME Errors

Obviously, with anything of this nature errors are going to occur. The ACME protocol uses a standardized format for reporting these errors. It’s called a problem document (RFC 7807) and in its “type” field the server arranges a series of tokens that provide information as to what the problem is.

The string looks like this:

urn:ietf:params:acme:error:

When you see the word “token,” the ACME RFC is using the term to describe the inputs between each one of those colons.

Thus, API clients can be informed of both the high-level error class (using the status code) and the finer-grained details of the problem (using one of these formats).

The portion of that string we’re going to focus on is the “error” token. Here’s a quick list of the possible errors and what they mean. Many of these can be corrected by the ACME client itself. Some may involve human intervention.

Error Tokens

Type	Description
accountDoesNotExist	The requested account does not exist
alreadyRevoked	The requested certificate has already been revoked
badCSR	The CSR was generated incorrectly (non-compliant)
badNonce	The nonce generated was insufficient
badPublicKey	The server doesn’t support the public key that signed this
badRevocationReason	The requested revocation lacks a valid reason
badSignatureAlgorithm	The server doesn’t support the algorithm that was used to sign this
caa	Issuance forbidden by a CAA record
compound	Specific error conditions are indicated in the “subproblems” array
connection	The server couldn’t connect to the validation target
dns	There was a problem with the DNS query during validation
externalAccountRequired	The request is missing a value in the “externalAccountBinding” field
incorrectResponse	The client returned and incorrect response to a validation challenge
invalidContact	A contact URL for your account was invalid
malformed	The request message was malformed
orderNotReady	Self-explanatory
rateLimited	The request exceeds a rate limit
rejectedIdentifier	The server will not issue certificates for this domain
serverInternal	The server experienced an internal error
tls	A TLS error occurred during validation
unauthorized	The client isn’t authorized to make this request
unsupportedContact	A contact URL for your account used an unsupported protocol scheme
unsupportedIdentifier	Self-explanatory
userActionRequired	Manual intervention is required at the “instance” URL

ACME Challenges

Validation is one of the trickiest things Certificate Authorities are asked to do. There is no fool-proof single method for validating control over a domain or identifier – or at least none that have been standardized – instead CAs rely on a patchwork of validation checks for confirming whether an entity has control. The ACME protocol allows for this by offering different types of challenges that can verify control.

While there were originally three challenges available when ACME v1 first came into use, today one has been deprecated. A third challenge type is being designed, but it’s a fairly high-level standard that’s intended more for large hosting providers.

HTTP Challenges

The CA sends your ACME agent a token to install on the server. The agent creates a file that contains said token along with a thumbprint of the authorization key that was generated during setup. The two are “concatenated” which is a fancy five dollar word for putting two things end-to-end.

(Token) || '.' || (Thumbprint of Authorization Key)

Once the file is installed, the agent informs the CA, which tries to retrieve it.

DNS Challenges

This challenge requires your ACME agent to place a given value in a TXT record in your domain’s DNS space. Like with HTTP challenges, the CA provides the agent a token, which is concatenated with the thumbprint of the authorization key to create the TXT file. Once the agent notifies the CA that the challenge has been met, the CA attempts to make a DNS lookup and retrieve the TXT record.

TLS-SNI-01 & TLS-ALPN-01

We’re just going to give these a quick look. SNI-01 was deprecated back in March because there were some security concerns about it. It worked by facilitating a TLS handshake on port 443 and sending a specific SNI (Server Name Indication) header. TLS-ALPN-01 is similar, and is currently being made into its own standard, but it represents a level of complexity that most organizations aren’t all that excited to jump into.

How long does it take to satisfy these challenges?

This all happens behind the scenes very quickly. And the agent does all the work. There are a few suggestions made in the RFC though:

• Clients shouldn’t respond to challenges until they’re sure that the server’s queries will succeed.
• If the initial attempts fail, the CA’s server will allow your agent to retry. It’s advised not to retry more than once every 5-10 seconds though.
• The CA will view the challenge as “in progress” as long as the agent continues trying.
• There may be a small delay in between uploading the file or DNS record, and the CA being able to retrieve them.

Keep in mind though, we’re speaking about time in a digital context that tracks some functions in milliseconds. Realistically, most of these challenges are satisfied in well under 15 seconds.

I thought ACME only issued DV SSL certificates

Nope. That’s just the only way it’s ever been used. But ACME can also be used to requisition high-value, business authentication certificates as well. Obviously, you need to have some sort of existing business relationship with the CA you’re using. In Sectigo’s case it will be any sort of account with a balance or a payment agreement.

The protocol still works completely the same, there are just a couple of things that happen independently alongside of what the ACME protocol is doing.

Alongside setting up the ACME client and configuring it to contact your chosen CA, your organization undergoes either organization or extended validation – whatever you choose. That validation information stays good for 24 months. Once that’s complete, anytime a domain needs a certificate, the agent can contact the CA, satisfy the domain challenge and get the certificate issued.

Switching CAs is easy with ACME

One of the biggest advantages to using the ACME protocol, which is likely going to see wide use now that commercial CAs are beginning to support it, is that it’s easy to switch between CAs on the fly.

You literally just have to make an account with the new CA and then switch the URL or IP address that the agent is contacting.

After a quick authorization, the agent does the rest, replacing the old certificates with new ones from the new CA.

Sectigo plans to have a full rollout for its ACME protocol support this summer. DigiCert announced it was adding support earlier this year.

As always, leave any comments or questions below…

• #ACME
• #Sectigo