ACME Challenge Types #

ACME challenges provide the CA with assurance that certificate requesters control the identifiers (domain name or IP address) requested to be included certificates. To successfully complete challenges, clients must prove that they control the identifiers in question and, for most challenge types, clients must also prove that they hold the private key of the account key pair used to respond to the challenges.

ACME challenges typically require the client to set up some network accessible resource that the CA can query (via DNS or HTTP) from multiple vantage points worldwide in order to validate that the client controls an identifier. Once the challenge is validated, the client should de-provision the resource.

If the CA queries the resource too early, for example before the information had time to propagate globally, the validation may fail. This is why clients should only ask the CA to validate challenges once they believe the request will succeed. This is particularly important since some CAs refuse to retry failed challenge validations!

Most ACME challenges make use of a “key authorization string”. This string concatenates the CA-provided token for the challenge with the base64URL-encoded ACME account key SHA-256 JSON Web Key (JWK) Thumbprint, separated by a “.” character.

keyAuthorization = token || '.' || base64url(sha256-jwk-thumbprint(accountKey))

The sha256-jwk-thumbprint step indicates the computation specified in RFC 7638, using the SHA-256 digest algorithm.

http-01 #

The http-01 challenge type requires the client to provision a file, with a specific content, at a specific path on a web server. The file must be available over HTTP on TCP port 80, and not just HTTPS.

The URL at which the file must be provisioned is http://{domain}/.well-known/acme-challenge/{token}. Its content must be the ASCII representation of the key authorization.

See RFC 8555 and the excellent summary from Let’s Encrypt for more information about the http-01 challenge type and its pros/cons.

dns-01 #

The dns-01 challenge type requires the client to provision a TXT resource record containing a designated value on DNS. The value is the SHA-256 digest of the key authorization, and the validation record name is _acme-challenge.{domain}.

The dns-01 challenge type can be used to issue certificates containing wildcard domain names, but it can’t be used to issue certificate containing IP addresses.

See RFC 8555 and the excellent summary from Let’s Encrypt for more information about the dns-01 challenge type and its pros/cons.

dns-account-01 #

The dns-account-01 challenge type is still a draft RFC at the moment. As such, it isn’t widely supported by ACME CAs and ACME clients.

The dns-account-01 challenge type is almost the same as dns-01. The main difference is that the validation record name is not just _acme-challenge.{domain}. Instead, it contains an extra label derived from the ACME account URL. For example: _ujmmovf2vn55tgye._acme-challenge.{domain}.

The dns-account-01 challenge type can be used to issue certificates containing wildcard domain names, but it can’t be used to issue certificate containing IP addresses.

The dns-account-01 challenge type enables multiple independent systems to authorize a single domain name concurrently since it relies on a different DNS validation record name for each ACME account. The dns-account-01 challenge type avoids CNAME delegation conflicts inherent to dns-01. This is particularly valuable for multi-region or multi-cloud deployments that wish to rely upon DNS-based domain control validation and need to independently obtain certificates for the same domain.

See this article from Fastly for more information about the dns-account-01 challenge type and its pros/cons.

dns-persist-01 #

The dns-persist-01 challenge type is still a draft RFC at the moment. As such, it isn’t widely supported by ACME CAs and ACME clients.

The dns-persist-01 challenge type requires the client to provision a TXT resource record on DNS that identifies a CA and an account authorized to request certificates for that domain. The validation record name is _validation-persist.{domain} and the value must be formatted like a CAA resource record. For example:
pki.goog; accounturi=https://dv.acme-v02.api.pki.goog/account/G5TNiqAfNGyiyHC6wibmCA.

Unlike other challenge types, dns-persist-01 doesn’t require updating a network accessible resource during domain validation nor de-provisioning the resource upon validation. With dns-persist-01, the network accessible resource only has to be provisioned once and never needs to be updated afterward.

The dns-persist-01 challenge type can be used to issue certificates containing wildcard domain names and certificates containing IP addresses.

For IP validating addresses, the validation record name is
_ip-validation-persist.{reverse-zone-domain-name}. For example:
_ip-validation-persist.4.3.2.1.in-addr.arpa for the IPv4 address 1.2.3.4.

See this article from DigiCert for more information about the dns-persist-01 challenge type and its pros/cons.

tls-alpn-01 #

The tls-alpn-01 challenge type requires to construct a self-signed certificate containing a designed value, and serving it to clients negotiating the “acme-tls/1” application-layer protocol in the ALPN (Application Layer Protocol Negotiation) extension during the TLS handshake when connecting to TCP port 443.

The self-signed certificate must contain the domain name being validated as a dnsName in the subjectAlternativeName extension, and it must include the acmeIdentifier extension which must contain the SHA-256 digest of the key authorization.

See RFC 8737 and the excellent summary from Let’s Encrypt for more information about the tls-alpn-01 challenge type and its pros/cons.