ACME Basics

step-ca supports the Automated Certificate Management Environment (ACME) protocol. You can get X.509 certificates from your own certificate authority (CA) using popular ACME clients and libraries, or via the step command's built-in ACME client.

ACME is a modern, standardized protocol for automatic validation and issuance of X.509 certificates from a CA to clients.

In this document

Requirements

Overview

Why ACME?

With ACME, machines can get certificates from a CA without any human interaction involved.

For example, you can:

A Typical ACME Flow

Here's how an ACME client might request an X.509 certificate from a CA.

The ACME API for certificate requests requires an HTTPS connection between the client and CA.

ACME Challenge Types

There is not a single standard way to prove control over an identifier, so the core ACME specification makes this an extension point. Today, most commonly, ACME clients respond to challenges via HTTP, DNS, or TLS protocols.

A Device ID may be a device's serial number, or another identifier assigned at manufacture.

The HTTP Challenge (http-01)

The ACME CA challenges the client to host a random number at a random URL under /.well-known/acme-challenge on port 80. The CA verifies client control by issuing an HTTP GET request to that URL.

When To Use It

This is a good general-purpose challenge type. By hosting the challenge response via HTTP on port 80, the client proves its control over a protected port on the domain being requested. The http-01 challenge type is the easiest to set up, because any web server will let you host the challenge response as a static file.

The DNS Challenge (dns-01)

The ACME CA challenges the client to provision a random DNS TXT record for the domain in question. It verifies the challenge by querying DNS for that TXT record.

When To Use It

The dns-01 challenge type is good if your ACME server cannot reach the requested domain directly. The server only needs to be able to perform a DNS lookup to confirm the challenge. However, because the ACME client needs to modify DNS records, configuring a dns-01 client is usually more involved.

The TLS ALPN challenge (tls-alpn-01)

The ACME CA uses TLS to validate a challenge, leveraging application layer protocol negotiation (ALPN) in the TLS handshake. The client presents a self-signed TLS certificate containing the challenge response as a special X.509 certificate extension.

When To Use It

This challenge type is useful when a security policy requires the CA to reach the client via a TLS connection. This is a popular challenge type in cases where an ingress controller fronts clients attempting to receive a certificate.

The Device Attestation Challenge (device-attest-01)

You can use device-attest-01 for Apple Managed Device Attestation (MDA) and other secure zero-touch provisioning (SZTP) applications as part of your device management (MDM) strategy. step-ca supports attestation challenges using Apple devices and YubiKeys.

Certificates identify specific hardware devices, via permanent device IDs. These are typically client certificates that can be used for device authentication.

Configure step-ca for ACME

Let's get an X.509 certificate via the ACME http-01 challenge, using step-ca.

First, add an ACME provisioner to your step-ca configuration to enable ACME support:

You may need to restart step-ca to pick up the configuration changes.

Finally, use step as an ACME client to request a certificate. The client will start a web server on port 80 to respond to the ACME challenge.

Output:

Next Steps